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?
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.
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