Javadoc em Java

Documente um metodo com um comentario especial para que leitores e ferramentas vejam o que ele recebe e o que devolve. Em Yard.java, escreva um metodo add que recebe int x e int y e devolve a soma. Coloque um bloco /** */ direto acima de add. Dentro do bloco, descreva o trabalho em uma frase curta, depois marque cada parametro com @param e o resultado com @return. Em main, imprima add(10, 2). Compile com javac Yard.java e rode java Yard. A tela deve mostrar 12. Deixe as regras de naming para a pagina seguinte — esta licao e a forma do comentario de documentacao, nao a escolha de nomes.

Coloque /** acima do metodo

A pagina de debugging imprimiu valores para achar uma soma errada. Esta pagina escreve um comentario de documentacao acima de um metodo limpo. Abra Yard.java. Mantenha o nome da classe publica Yard. Apague rotulos println de debug sobrando que enterram a historia de documentacao, demos sobrando de equals / ==, arquivos horn de Machine sobrando, e qualquer Scanner de teclado. O programa nao deve esperar digitacao. Nenhuma linha import e necessaria nesta demo.
Dentro de Yard, mantenha um metodo pequeno e um main curto. O bloco de documentacao deve ficar imediatamente acima do metodo que descreve. Uma linha em branco entre o */ de fechamento e a linha do metodo e aceitavel. Nao esconda o bloco dentro de main. Nao coloque o bloco sob o corpo do metodo.
Escreva a abertura do comentario com duas estrelas depois da barra:
/**
Depois escreva uma frase simples que diga o que add faz. Depois escreva as tags. Feche com:
*/
O metodo em si continua Java comum:
static int add(int x, int y) {
return x + y;
}
Javadoc nao muda como return funciona. Diz ao leitor o que o metodo promete antes de ler cada linha do corpo.

Da pasta que guarda Yard.java, rode javac Yard.java. Quando parenteses, chaves e ponto e virgula baterem, javac nao escreve linha propria. Depois rode java Yard — nao java Yard.java. Tire o final .java do comando de execucao. Mantenha uma classe publica no arquivo para o nome bater com Yard.
A tela mostra 12. Percorra a execucao uma vez. Java comeca em Yard.main. A chamada add(10, 2) entra no metodo com x valendo dez e y valendo dois. A linha return devolve doze. System.out.println escreve esse numero. O bloco Javadoc nao imprime sozinho. O bloco e para leitores e ferramentas de documentacao. A prova iniciante nesta pagina ainda e uma execucao correta depois de um comentario claro.
Leia o bloco de comentario enquanto olha a assinatura do metodo. A frase Adds two numbers. bate com o trabalho de return x + y;. A linha @param x first number nomeia o primeiro parametro. A linha @param y second number nomeia o segundo parametro. A linha @return the sum of x and y nomeia o resultado. Mantenha a grafia das tags exata: @param e @return usam o sinal @ e letras latinas.
Se ainda vir x=10 e y=2 e depois 8 de um arquivo de debugging, mude para o arquivo de ensino de Javadoc e rode java Yard de novo. Se voce so escrever // Adds two numbers. acima do metodo, escreveu um comentario de linha comum, nao um bloco Javadoc. Mantenha a forma de duas estrelas /** para que o bloco seja documentacao, nao uma nota de uma linha.
Diga a regra em voz alta enquanto olha a tela: documente acima do metodo, marque os parametros, marque o retorno, depois compile e rode para provar que o metodo ainda funciona. Nao invente aulas longas de naming nesta pagina. Naming espera a proxima licao.

Leia o mapa das tags

Uma tabela curta guarda as tres pecas que voce digitou no comentario. A abertura /** */ marca um bloco de documentacao. @param descreve um nome de parametro. @return descreve o valor que o metodo devolve. Mantenha o nome do metodo add e a chamada add(10, 2) para a tela ficar um unico numero claro.
A tabela e o mapa curto desta pagina. Primeiro voce coloca o bloco. Depois marca entradas e saida. Depois verifica com javac e java Yard. Pule o chute de que qualquer estilo de comentario e Javadoc. Pule apagar o bloco antes de saber que o programa ainda imprime 12.

Mantenha a tabela ao lado do arquivo de ensino enquanto edita. Aponte para @param x no arquivo, depois para int x na assinatura. Aponte para @param y, depois para int y. Aponte para @return, depois para a linha return. Esse jogo de combinar e a ideia iniciante inteira em uma passagem. Ferramentas que leem Javadoc procuram essas tags. Leitores humanos usam o mesmo mapa quando o corpo do metodo cresce depois.
Se demos de debugging sobrando ainda ficarem por perto, guarde-as como historia. Para esta licao rode o arquivo de ensino de Javadoc para a tela mostrar 12 de add, nao linhas rotuladas x= de uma caca. Se javac reclamar de classes publicas duplicadas, mantenha so Yard public.

// comum nao e Javadoc

Uma linha que comeca com // e uma nota para quem le o arquivo. E util, e este curso ja usou comentarios de linha antes. Nao e a forma de bloco de documentacao que esta pagina ensina. Javadoc para um metodo comeca com /** e termina com */. As tags @param e @return ficam dentro desse bloco.
Se voce colocar uma string simples sob o metodo depois de outras instrucoes, essa string nao e documentacao do metodo. O bloco de documentacao deve ser o comentario preso acima do metodo. Mantenha o bloco colado em add. Mantenha main livre de teatro falso de documentacao. A chamada em main continua um print normal da soma devolvida.
Quando o comentario esta errado mas o corpo do metodo esta certo, javac ainda pode ter sucesso e java Yard ainda pode imprimir 12. Por isso esta pagina pede que voce leia o comentario e a assinatura juntos, nao so a tela. A tela prova a matematica. O comentario prova que voce rotulou o contrato.

Comparado com prints de debugging

Na pagina de debugging, println respondeu o que seus numeros realmente eram quando uma soma parecia errada. Nesta pagina, Javadoc responde o que add promete antes de o leitor mergulhar no corpo. Voce ainda compila Yard.java e roda java Yard. Os tokens novos sao /**, @param e @return acima de um metodo.
Debugging usou saida comum como lanterna. Javadoc usa um comentario estruturado como rotulo na porta do metodo. Quando o rotulo bate com os parametros e o retorno, leitores perdem menos tempo chutando. Quando o rotulo falta, o programa ainda pode rodar — o habito de documentacao ainda falta.
Se um arquivo de debugging sobrando ainda estiver aberto, voce pode ver x=10, y=2 e uma soma antiga. Mude para o arquivo Javadoc para que main imprima add(10, 2) e o metodo carregue o bloco de documentacao. Mantenha aulas de estilo de naming fora desta pagina. Mantenha entrada de teclado fora desta pagina.

Antes de naming

Voce pode colocar /** */ acima de add, marcar @param x, marcar @param y, marcar @return, e ainda ver 12 depois de java Yard. Compile Yard.java e rode java Yard para a demo mantida. O comentario contou o contrato aos leitores. A pagina seguinte e naming, onde voce escolhe nomes claros para o que escreve.
Mantenha a demo add documentada para um par claro de comentario-mais-execucao. Mantenha arquivos de debugging fora desta pagina quando praticar documentacao. Mantenha arquivos de naming fora desta pagina ate aquela licao. Esses tres habitos sao o checkpoint antes de seguir. Quando as tags baterem com a assinatura e a tela mostrar 12, Javadoc fez o trabalho desta licao e voce esta pronto para o proximo topico sobre naming.
Uma ultima passagem pela pasta: um Yard public, um add documentado, um print em main, sem espera de teclado, sem regras de naming forcadas. Rode javac Yard.java e java Yard mais uma vez na demo que voce mantem aberta. Se a tela ainda mostrar 12 e o comentario ainda ficar acima de add com @param e @return, a forma de documentacao esta solida e o curso pode ir para naming na pagina seguinte. Prefira um bloco de documentacao claro em um metodo para que cada leitura ensine o mesmo mapa.