Danilo S. Carvalho, Ph.D. Assistant Professor - Computer Programming / AI / NLP

Introdução ao Javadoc - Comp II (DCC - UFRJ)

A documentação oficial da linguagem java pode ser encontrada no endereço:

https://docs.oracle.com/en/java/javase/12/

onde podem ser encontradas as informações sobre a JRE, JDK, e as especificações da linguagem e ferramentas.

Em particular, todos os pacotes da biblioteca padrão podem ser consultados em

https://docs.oracle.com/en/java/javase/12/docs/api/index.html

incluindo informaões como o nome do pacote, nome da classe, nome dos métodos e atributos, e explicações sobre o seu funcionamento.

Mas como toda essa documentação é produzida?


Javadoc

O Javadoc é um gerador de documentação que produz páginas em formato HTML, tais como a documentação oficial, a partir de informação colocada em comentários no código fonte, em um certo formado chamado “doc comments”.

Como o nome sugere, o Javadoc foi criado para produzir a documentação da linguagem Java, mas a ideia foi adotada por programadores de outras linguagens de programação (C/C++, Python, JavaScript, entre outras), que hoje em dia possuem seus geradores de documentação similares ao Javadoc.

Estrutura básica

Os comentários Javadoc são sempre escritos em comentários multi-linha, onde a abertura do comentário é feita com /** (dois asteriscos) em vez de /*. Os campos pertinentes à documentação desejada são declarados com @<nome do campo>. Por exemplo, para classes:

// imports

/** Classe de exemplo para o uso de Javadoc.  (Descrição curta de uma linha)
 * <p>
 * Descrição detalhada da classe.
 * </p>
 * @author      Nome Sobrenome <address @ example.com>
 * @version     1.0                 (versão atual dessa classe)
 * @since       0.9          (versão onde essa classe foi incluida no código)
 */
public class ExemploJavadoc {
    // corpo da classe
}

Para métodos, podemos escrever uma descrição do objetivo da função, a descrição de cada parâmetro e também do retorno. Por exemplo:

/**
 * Soma dois números inteiros.   (Descrição curta de uma linha)
 * <p>
 * Essa função aceita dois números inteiros como entrada   
 * e retorna a soma de ambos.   (Descrição mais detalhada)
 * </p>
 * Mais explicações aqui...
 *
 * @param  a Primeiro operando.
 * @param  b Segundo operando.
 * @return A soma dos dois operandos.
 */
public int soma (int a, int b) {
    // corpo do método
}

Variáveis também podem ser documentadas:

/**
 * Valor da constante PI: A razão da circunferência de um círculo pelo seu diâmetro.
*/
const double PI = 3.1415926535

Para gerar a documentação, deve-se usar o programa javadoc, incluso na JDK, ou a opção correspondente na IDE de sua escolha. Usando pela linha de comando:

javadoc -subpackages -sourcepath <diretório onde estão os fontes> <lista pacotes a serem documentados>

A lista e descrição de todos os campos que podem ser usados no Javadoc pode ser consultada em

https://docs.oracle.com/en/java/javase/13/docs/specs/javadoc/doc-comment-spec.html