Sem medo do JavaDoc

O “JavaDoc” falando em termos gerais, é um gerador de documentação que a sun criou para ser utilizado por programadores, para documentar todo o código fonte visível de uma aplicação. Fazer o javadoc da aplicação que você está fazendo é muito importante, tanto para você quanto para outros programadores que utilizarão o seu programa, por exemplo, se você estiver fazendo uma biblioteca (jar), se não tiver javadoc quem for utilizar o seu jar estará perdido, e até você mesmo poderá se perder quando estiver melhorando ou fazendo algum ajuste no código, eu mesmo esqueço qualquer lógica que eu tenha criado a mais de algumas horas, por isso todo código que eu faço é muito bem comentado e documentado, isso não me toma muito tempo e é bom fazer isso enquanto o método está sendo criado, por que a regra de negócio dos métodos e das classes ainda estão na memória (na sua memória). Vamos para um exemplo prático!
Para poder comprovar o  efeito do javadoc, você vai precisar de uma ide. Se você já manipulou arquivos em java, precisou em algum momento definir delimitadores de diretórios “/” para unix e “\” para windows. Mas você não precisa fazer um código pra descobrir o sistema operacional do usuário do seu programa, o java já te informa tudo o que você precisa do sistema operacional utilizado pelo usuário, com o código System.getProperty(), esse método recebe uma String, que indica qual propriedade do sistema operacional você quer, mas eu não sei o que eu tenho que informar, eu sei apenas que eu quero um “separador de diretórios”, então o que fazer? Escreva na sua IDE, dentro de algum método java.lang.System.getProperty(“”), esse método não vai nos servir pra nada, por que não informamos qual a propriedade do sistema que queremos, mas não se desespere, a sun faz JavaDoc. Selecione o método getProperty e aperte a tecla F2 (eclipse) ou apenas coloque o mouse sobre o método até aparecer uma janelinha conforme abaixo. Está ai, tudo o que o método faz, explicado em cada detalhe, da até pra navegar.
Se descer mais um pouco a barra de rolagem vai ver alguns links na seção “See Also“, clique no link “getProperties()“, um outro javadoc vai aparecer, mas agora o javadoc do método getProperties, contendo todas as possíveis variáveis que devem ser informada no método getProperty, no nosso caso seria a “file.separator”, mas olha como tem várias variáveis que podemos utilizar, legal né? Essa não é a unica forma de ver um javadoc, da também para ver de uma forma geral em um navegador. Quando você termina o seu projeto, se ele estiver com todos os javadocs criados, você pode “exportar” essa documentação para o formato html e ele fica exatamente dessa forma: http://download.oracle.com/javase/6/docs/api/ Esse é o javadoc da JRE/JDK, a documentação, da linguagem java. Seu programa pode ter uma documentação exatamente igual a essa, se você documentar os métodos corretamente. Percebeu a importância do javadoc? Apenas os javadocs de objetos “public” são exportados ou ficam visíveis, mas sempre documente todos os seus métodos mesmo private, afinal nunca se sabe quando você vai precisar dessa documentação, e existe a opção de exportar a documentação de objetos private e protected também, mas vamos ver isso mais adiante. Um javadoc não difere em nada de um comentário de bloco /* comentário de bloco  */ a diferença é que ele começa com dois asteriscos /** javadoc */, até a cor muda, se você não alterou as cores da sua ide, um comentário normal, começando com um asterisco, tem a cor diferente de um comentário javadoc, que começa com dois asteriscos. Um javadoc aceita tags HTML, e eu aconselho escrever o javadoc como se estivesse fazendo uma página web mesmo, mas não precisa de comandos complexos, ficar alinhando criando div, nada disso, vamos ser simplistas, limite-se a usar negrito <b></b>, itálico <i></i>, sublinhado <u></u>, tabelas se necessário <table><tr><td></td></tr></table>, parágrafos <p></p> e quebras de linha <br>, mais que isso já é desnecessário. Os links são criados automaticamente com tags próprias. O javadoc tem alguns comandos próprios para definirmos coisas como versão, autor, descrever os parametros e o retorno, explicar as exceções que são lançadas, entre outros. Todos os comandos javadoc começam com @. Exemplo prático

/** 
* Método principal 
* <p>Esse método executa alguma ação</p> 
* @param args, um vetor de argumentos que podem ser informados 
* @author coreerror 
* @exception Vai ser lançada uma NullPointerException 
* @version 1.0.1 
* @return Vai ser retornada uma lista de String 
*/
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Esse comentário azul antes do método é o javadoc, nele eu coloquei o nome do método, coloquei também em um parágrafo informando o que o método faz, expliquei os parâmetros com a tag @param, falei que fez esse método com a tag @autor, expliquei as exceções com a tag @exception, indiquei a versão do método com @version e disse também o que o método irá retornar com @return. Não repare que o javadoc não tem nada a ver com o método, isso ai é só pra exemplificar, eu sei que o método não retorna nada e não lança nenhuma exception. Se você colocar o mouse sobre a palavra main (o nome do método), vai ver esse comentário sendo exibido como um javadoc:

Existe também a tag @see, essa tag deve ser utilizada quando você quer que o javadoc de outro método ou classe seja visto, e um link vai ser criado automaticamente para o método ou classe que você indicou, lembra que no javadoc do System.getProperty você clicou no link getProperties? É exatamente isso, sempre coloque @see para as dependencias do seu método, para as classes que devem ser informadas por parâmetro para seu método, se ele receber objetos, ou em caso de classes, coloque @see para os construtores e para oturas classes que trabalham em conjunto com ela, etç. Quando você quer referenciar um método de alguma classe no javadoc você não deve utilizar o ponto @see System.getProperty, mas sim um “sustenido“, também conhecido como “jogo da velha” @see System#getProperty, isso também vale para referenciar métodos ou variáveis que estiverem na mesma classe @see #outroMetodo() @see #algumaVariavel

/** 
* @see System 
* @see System#getProperty(String) 
* @see #getClass() 
*/
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Se você quer criar um link em algum lugar que não seja a seção “See Also” você também pode, por exemplo, se na parte que você está explicando o que o método faz e como ele funciona você já quiser ir linkando as classes e métodos envolvidos, basta utilizar o comando {@link Classe}, com chaves e tudo, no lugar da palavra “Classe” você coloca o nome da classe ou da Classe#Método.

/** 
* Método principal 
* <p>Esse é um método da classe {@link MainClass} e 
* acessa a classe {@link System}</p> 
*/ 
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Para exportar o javadoc e criar um site igual ao da sun que está linkado mais acima você pode ir da forma menos chata, pela IDE, clicar com o botão direito sobre o projeto e selecionar a opção Exportar, depois escolhe Java/JavaDoc na caixa de diálogos que irá abrir, nas telas seguintes seleciona as opções da documentação, onde os arquivos serão salvos, quais classes participarão desse documento, se você quer a documentação dos componentes public, protected, private ou apenas a documentação dos pacotes, da pra selecionar os jars envolvidos na sua aplicação e várias outras opções. Mas se você é guerreiro, pode ir pelo console e utilizar o comando “javadoc”, dentro da pasta onde suas classes estão. Ex.:

javadoc -d doc c:\home\codeerror\projetoTeste\src\*.java

Todos as opções que podem ser selecionadas através da IDE também podem ser indicadas na linha de comando, são inúmeras opções, sugiro digitar no console “javadoc -help” para analisar as que você precisa. Agora que você está craque em javadoc, vai colocar em cada código que fizer, vou colocar uma pequena tabela abaixo com os comandos mais relevantes e pra que eles servem.

@author	Nome de quem fez o código
@category	Você pode criar categorias para seus códigos, como “utilidades” ou “maipulação” ou “services”, etç,
@deprecated	Informa se esse método está depreciado, ou seja, irá deixar de existir na próxima versão do programa
@exception	Indica as exceções que podem ser lançadas pelo método/Classe
@param	Explica o parâmetro, deve ser criado um @param para cada parametro recebido pelo método. Tente explicar detalhadamente, como por exemplo “Informar o objeto X com todas as variáveis preenchidas” ou “informar um numero de 0 a 10?
@return	Explica o que será retornado pelo método, indique também as possíveis variações de retorno, como “pode retornar verdadeiro se 1 for menor que 2 ou falso se 2 for maior que 1?.
@see	Cria um link de referência para outra classe ou método
@since	Esse é para controle de versão, aqui você informa quando o método foi adicionado na classe, ou quando a classe foi adicionada ao pacote
@throws	Similar a @exception
@version	Aqui você pode indicar a versão da classe ou do método
{@link XX}	Cria um link para uma classe ou método, o nome da classe ou método deve ser colocado no lugar das letras “XX”

Enjoy!