Como documentar seu código Java?

Javadoc é uma ferramenta de documentação para a linguagem Java que permite documentar o código por meio de comentários específicos e ao final ainda é possível gerar um HTML personalizado contendo tudo o que foi documentado (classes, métodos, atributos etc.). Essa ferramenta normalmente vem junto com a instalação da JDK.

Os comentários sempre possuem uma descrição, uma tag e a descrição dessa tag, e devem estar acima do trecho de código que será documentado, existem diversas tags de comentários, algumas populares:

@author - informa o(s) responsável(veis) por aquele código, ou seja, o(s) nome(s) do(s) desenvolvedor(es)

@version - diz qual versão está o código

@param + nome do parâmetro - define do que se trata aquele parâmetro de um determinado método

@return - documenta qual o retorno de um método

Exemplo básico de utilização em um método:

/** 

* Realiza um depósito na conta 
* @param agencia A agencia da conta 
* @param numero O numero da conta com digito
* @param valor O valor que será depositado
* @return Confirmação da operação de depósito

*/
public String depositar(int agencia, long numero, double valor) {

}

Analisando o código acima, parece óbvio do que se trata esse método e seus parâmetros só pelo nome deles, porém o óbvio nem sempre é o óbvio para outra pessoa que irá programar nesse código, por isso que a documentação é importante, ainda mais quando se trata de uma aplicação complexa e extensa.

Após a inserção dos comentários através de qualquer IDE é possível gerar o documento em HTML do javadoc, sugiro pesquisar como funciona na IDE de sua utilização, o processo é bem simples e feito pela interface gráfica da IDE.

Bônus: extensão que facilita a documentação no IntelliJ: Easy Javadoc

Espero que tenha conseguido entender um pouco mais sobre como documentar seu código em Java, se tiver alguma dúvida, crítica ou correção, por favor deixe nos comentários.

Referência: https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

Fonte da imagem do banner: https://www.konakart.com/documentation/javadoc/