Documente seu código Java automaticamente com Javadoc

Se você faz qualquer tipo de programação, sabe que uma das tarefas mais tediosas envolvidas é documentar seu código. Se você acha isso um pouco irritante ou um empreendimento que você enfrenta com medo absoluto, a documentação do código é essencial. Outros precisam entender como seu código funciona, e você pode até ser um deles se estiver lendo-o posteriormente!

Java fornece convenientemente uma solução integrada para o problema: Javadoc.

Javadoc pode ajudá-lo a documentar seu código automaticamente

Espero que você já siga boas práticas de codificação e inclua comentários explicativos em seu código. Embora esse tipo de comentário no código seja certamente útil, ele não fornece nada comparável a um manual.

Claro, outro programador pode examinar seu código e ler sobre as classes, métodos e funções específicos que estão na frente dele. No entanto, é extremamente difícil obter uma boa visão geral de todo o código ou encontrar funções que possam ser úteis quando você não sabe que elas existem. Javadoc visa resolver esse problema.

Javadoc irá gerar um manual HTML detalhado e fácil de ler para todo o seu código automaticamente. O melhor de tudo, ele faz isso usando comentários de código que você provavelmente já está escrevendo.

O que exatamente é Javadoc e como ele funciona?

Javadoc é um programa autônomo que vem junto com as versões do kit de desenvolvimento Java (JDK) da Oracle. Na verdade, você não pode baixá-lo separadamente. Ao baixar e instale uma das versões do JDK da Oracle, ele também instalará o Javadoc.

Ao executá-lo, o Javadoc gera documentação HTML a partir de comentários especialmente formatados em seu código-fonte Java. Esse processo cria uma documentação mais útil e legível, ao mesmo tempo em que incentiva as melhores práticas.

Em poucas palavras, o Javadoc possibilita que você escreva seu código e sua documentação ao mesmo tempo. Simplifica seu fluxo de trabalho e permite que você faça um uso mais eficiente do seu tempo.

Javadoc funciona analisando comentários especialmente formatados em seu código e convertendo-os em saída HTML. A única mudança que você realmente precisa fazer é incluir certas strings em seus comentários. Eles permitem que o Javadoc saiba o que você deseja incluir na documentação final.

Comentários Javadoc devem preceder imediatamente uma classe, campo, construtor ou declaração de método. O comentário em si deve:

• Comece com os três caracteres /**.
• Inclua um asterisco no início de cada nova linha.
• Feche com os dois personagens */.

Nos comentários, você pode incluir HTML na saída final e incluir tags que gerarão links para partes relevantes de sua base de código. Você pode até usar coisas como tags de imagem HTML para incluir imagens na documentação final. Depois de se acostumar com o formato e as tags disponíveis, escrever esses comentários é muito fácil.

Aqui está um exemplo para ilustrar comentários Javadoc simples que descrevem uma função que obtém uma imagem de um URL e a imprime na tela. O comentário precede imediatamente a função e descreve o que ela faz. Este bloco de comentários também faz uso de três tags específicas da seção: @param, @Retorna, e @Vejo.

/**
* Retorna um objeto Image que pode ser pintado na tela.
* O argumento url deve especificar um valor absoluto {@link URL}. O nome
* argumento é um especificador relativo ao argumento url.
* 

* Este método sempre retorna imediatamente, independentemente de o
* a imagem existe. Quando isto applet tenta desenhar a imagem no
* na tela, os dados serão carregados. As primitivas gráficas
* que desenha a imagem irá pintar incrementalmente na tela.
*
* @param url um URL absoluto que fornece a localização base da imagem
* @param nomeie a localização da imagem, em relação ao argumento url
* @Retorna a imagem no URL especificado
* @Vejo Imagem
*/
público Imagem getImage(URL URL, nome da string){
tentar {
Retorna getImage(novo URL(url, nome));
 } truque (MalformedURLException e) {
Retornanulo;
 }
}

Quando o Javadoc processa o código acima, ele gera uma página da Web semelhante à seguinte:

Um navegador renderiza a saída Javadoc da mesma forma que exibe qualquer documento HTML. Javadoc ignora espaços em branco extras e quebras de linha, a menos que você use tags HTML para criar esse espaço.

As @tags usadas no final do comentário geram a Parâmetros, Devoluções, e Veja também seções que você vê.

Você deve seguir o @param tag com o nome do parâmetro, um espaço e uma descrição do mesmo. No caso acima, existem dois parâmetros: URL e nome. Observe que ambos aparecem sob o mesmo título de Parâmetros na saída da documentação. Você pode listar quantos parâmetros forem necessários para a função ou método que você está descrevendo.

o @Retorna tag documenta o valor que a função retorna, se for o caso. Pode ser uma simples descrição de uma palavra ou muitas frases, dependendo das circunstâncias.

o @Vejo tag permite marcar outras funções relacionadas ou relevantes. Neste caso, a tag @see se refere a outra função chamada simplesmente Image. Observe que as referências feitas com essa tag são links clicáveis, permitindo que o leitor pule para o item referenciado no HTML final.

Há mais tags disponíveis, como @version, @author, @exception e outras. Quando usadas corretamente, as tags ajudam a relacionar os itens entre si e possibilitam navegar facilmente pela documentação.

Executando Javadoc em seu código-fonte

Você invoca o Javadoc na linha de comando. Você pode executá-lo em arquivos únicos, diretórios inteiros, pacotes java ou em uma lista de arquivos individuais. Por padrão, o Javadoc irá gerar os arquivos de documentação HTML no diretório onde você digitar o comando. Para obter ajuda sobre os comandos específicos disponíveis, basta digitar:

javadoc --ajuda

Para ver exatamente o que o Javadoc pode fazer com mais detalhes, confira a documentação oficial de Oráculo. Para criar um conjunto rápido de documentação em um único arquivo ou diretório, você pode inserir javadoc na linha de comando seguido por um nome de arquivo ou curinga.

javadoc ~/code/nomedoarquivo.java
javadoc ~/code/*.Java

Acima está uma lista dos arquivos e diretórios que o Javadoc criou. Como você pode ver, existem alguns deles. Por esse motivo, você deve ter certeza de que não está no mesmo diretório que seu código-fonte ao executar o programa. Fazer isso pode criar uma bagunça.

Para visualizar seus documentos recém-criados, basta abrir o index.html arquivo em seu navegador preferido. Você receberá uma página como a seguinte:

Esta é a documentação para uma única e curta classe Java para demonstrar a saída. O cabeçalho mostra o nome da classe, bem como os métodos incluídos nela. Rolar para baixo revela definições mais detalhadas de cada um dos métodos de classe.

Como você pode ver, para qualquer tipo de projeto Java, especialmente os grandes com muitos milhares de linhas de código, esse tipo de documentação é inestimável. Seria um desafio aprender sobre uma grande base de código lendo seu código-fonte. As páginas Javadoc tornam esse processo muito mais rápido e fácil de seguir.

Javadoc pode ajudá-lo a manter seu código Java e toda a documentação relevante organizada e fácil de usar. Se você está fazendo isso para o seu futuro eu esquecido ou para facilitar as coisas para uma grande equipe, Javadoc é uma ferramenta poderosa que pode mudar a maneira como você escreve e interage com sua codificação Java projetos.

Os 8 melhores blogs de Java para programadores

Leia a seguir