Javadoc

Javadoc é um gerador de documentação criado pela Sun Microsystems para documentar a API dos programas em Java, a partir do código-fonte. O resultado é expresso em HTML. É constituído, basicamente, por algumas marcações muitos simples inseridas nos comentários do programa.

Este sistema é o padrão de documentação de classes em Java, e muitas dos IDEs desta linguagem irão automaticamente gerar um Javadoc em HTML.

Ele também provê uma API para a criação de doclets e taglets, que permitem a análise da estrutura de um aplicativo Java. É assim, por exemplo, que o JDiff consegue gerar relatórios de alterações feitas entre duas versões de uma API.

Rodando Javadoc em Windows

Para documentar todas as classes em um diretório, rode a seguinte instrução na linha de comando (ou coloque-o em um arquivo BAT e execute-o). Dependendo do diretório de instalação na sua máquina, você deverá usar a linha baixo modificada, mas ela irá criar um diretório com a documentação de todas as suas classes:

"C:\Arquivos de programas\Java\jdk1.6.0\bin\javadoc" -d doc *.java

Por padrão, apenas os membros públicos são mostrados. Para ter uma visibilidade mais profunda, você pode usar os seguintes modificadores:

• -protected
• -package
• -private

Tags Javadoc

Os desenvolvedores usam certos estilos de comentários e tags Javadoc ao documentar códigos-fonte. Um bloco de comentário em Java iniciado com /** irá iniciar um bloco de comentário Javadoc, que será incluído no HTML gerado. Uma tag Javadoc começa com um "@" (arroba). Na tabela abaixo, algumas destas tags.

Tag	Descrição
@author	Nome do desenvolvedor
@deprecated	Marca o método como deprecated. Algumas IDEs exibirão um alerta de compilação se o método for chamado.
@exception	Documenta uma exceção lançada por um método — veja também @throws.
@param	Define um parâmetro do método. Requerido para cada parâmetro.
@return	Documenta o valor de retorno. Essa tag não deve ser usada para construtores ou métodos definidos com o tipo de retorno void.
@see	Documenta uma associação a outro método ou classe.
@since	Documenta quando o método foi adicionado a a classe.
@throws	Documenta uma exceção lançada por um método. É um sinônimo para a @exception introduzida no Javadoc 1.2.
@version	Exibe o número da versão de uma classe ou um método.

Para inserir o símbolo @ sem iniciar uma tag Javadoc você pode usar o código de caracter HTML @ e evitar problemas de parsing.

Exemplo

Segue-se um exemplo de uso do Javadoc para documentar um método. Note que o espaçamento e a quantidade de caracteres neste exemplo apenas seguem as convenções.

 /**
  * Valida um movimento de xadrez.
  * 
  * @param aColunaDe   Coluna atual da peça a ser movida
  * @param aLinhaDe    Linha atual da peça a ser movida
  * @param aColunaPara Coluna destino da peça a ser movida
  * @param aLinhaPara  Linha destino da peça a ser movida
  * @return            verdadeiro se o movimento é válido ou falso se inválido
  * @author            Joana Silva
  * @author            Nuno Martins
  */
  boolean validaMovimento(int aColunaDe, int aLinhaDe, int aColunaPara, int aLinhaPara)
  {
      ...  
  }

Ligações externas

• «Website do Javadoc» (em inglês)
• «Coleção de doclets Javadoc» (em inglês)
• «Motor de busca de Javadocs» (em inglês)