TOC

Introdução ao Javadoc

Introdução ao Javadoc

*1. Visão geral *

Uma boa documentação da API é um dos muitos fatores que contribuem para o sucesso geral de um projeto de software.

Felizmente, todas as versões modernas do JDK fornecem a ferramenta Javadoc - para gerar documentação da API a partir de comentários presentes no código-fonte.

Pré-requisitos:

  1. JDK 1.4 (o JDK 7+ é recomendado para a versão mais recente do plug-in Maven Javadoc)

  2. A pasta JDK /bin adicionada à variável de ambiente PATH

  3. (Opcional) um IDE que, com ferramentas internas

===* 2. Comentários Javadoc *

Vamos começar com comentários.

*A estrutura de comentários Javadoc é muito semelhante a um comentário comum de várias linhas* , mas a principal diferença é o asterisco extra no início:
//This is a single line comment

/*
 *This is a regular multi-line comment
*/

/**
 *This is a Javadoc
*/

Os comentários no estilo Javadoc também podem conter tags HTML.

2.1 Formato Javadoc

Os comentários do Javadoc podem ser colocados acima de qualquer classe, método ou campo que desejamos documentar.

Esses comentários geralmente são compostos de duas seções:

  1. A descrição do que estamos comentando

  2. As tags de bloco independentes (marcadas com o símbolo "_ @ _") que descrevem metadados específicos

Usaremos algumas das tags de bloco mais comuns em nosso exemplo. Para obter uma lista completa de tags de bloco, visite o referência de guia.

2.2 Javadoc no nível de classe

Vamos dar uma olhada em como seria um comentário do Javadoc em nível de classe:

/**
* Hero is the main entity we'll be using to . . .
*
* Please see the {@link com..javadoc.Person} class for true identity
* @author Captain America
*
*/
public class SuperHero extends Person {
   //fields and methods
}

Temos uma descrição curta e duas tags de bloco diferentes - autônoma e inline:

  • Tags independentes aparecem após a descrição com a tag como a primeira palavra de uma linha, por exemplo, a tag _ @ author_

  • As tags embutidas podem aparecer em qualquer lugar e estar entre colchetes , por exemplo, a tag _ @ link_ na descrição

Em nosso exemplo, também podemos ver dois tipos de tags de bloco sendo usadas:

  • _ \ {@ link} _ fornece um link embutido para uma parte referenciada do nosso código-fonte *_ @ author_ o nome do autor que adicionou a classe, método ou campo comentado

====* 2.3. * Javadoc em Campo Nível

Também podemos usar uma descrição sem nenhuma tag de bloco como esta dentro da nossa classe SuperHero:

/**
 *The public name of a hero that is common knowledge
*/
private String heroName;

Os campos particulares não terão o Javadoc gerado para eles, a menos que passemos explicitamente a opção -private para o comando Javadoc.

2.4. Javadoc em Nível do método

Os métodos podem conter uma variedade de tags de bloco Javadoc.

Vamos dar uma olhada no método que estamos usando:

/**
 *<p>This is a simple description of the method. . .
* <a href="http://www.supermanisthegreatest.com">Superman!</a>
 *</p>
* @param incomingDamage the amount of incoming damage
 *@return the amount of health hero has after attack
* @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 *@since 1.0
*/
public int successfullyAttacked(int incomingDamage) {
   //do things
    return 0;
}

O método successfullyAttacked contém uma descrição e várias tags de bloco independentes.

Existem muitas tags de bloco para ajudar a gerar a documentação adequada e podemos incluir todo tipo de informação. Podemos até utilizar tags HTML básicas nos comentários.

Vamos examinar as tags que encontramos no exemplo acima:

  • _ @ param_ fornece qualquer descrição útil sobre o parâmetro ou a entrada de um método que ele deve esperar

  • _ @ return_ fornece uma descrição do que um método retornará ou poderá retornar

  • _ @ see_ gerará um link semelhante à tag _ \ {@ link} _, mas mais no contexto de uma referência e não em linha

  • _ @ since_ especifica qual versão a classe, campo ou método foi adicionado ao projeto

  • _ @ version_ especifica a versão do software, comumente usada com macros% I% e% G%

  • _ @ throws_ é usado para explicar melhor os casos em que o software esperaria uma exceção *_ @ obsoleto_ fornece uma explicação de por que o código foi reprovado, quando pode ter sido reprovado e quais são as alternativas

Embora ambas as seções sejam tecnicamente opcionais, precisaremos de pelo menos uma para a ferramenta Javadoc para gerar algo significativo.

===* 3. Geração Javadoc *

Para gerar nossas páginas Javadoc, vamos dar uma olhada na ferramenta de linha de comando que acompanha o JDK e o plug-in Maven.

====* 3.1 Ferramenta de linha de comando Javadoc *

A ferramenta de linha de comando Javadoc é muito poderosa, mas tem alguma complexidade associada a ela.

A execução do comando javadoc sem nenhuma opção ou parâmetro resultará em um erro e nos parâmetros de saída esperados.

Precisamos especificar pelo menos para qual pacote ou classe queremos que a documentação seja gerada.

Vamos abrir uma linha de comando e navegar para o diretório do projeto.

Supondo que as classes estejam todas na pasta src no diretório do projeto:

[email protected]:~$ javadoc -d doc src\*

Isso irá gerar documentação em um diretório chamado doc, conforme especificado com o sinalizador –d. Se existirem vários pacotes ou arquivos, precisaríamos fornecer todos eles.

A utilização de um IDE com a funcionalidade incorporada é, obviamente, mais fácil e geralmente recomendada.

3.2 Javadoc com plug-in Maven

Também podemos fazer uso do plug-in Maven Javadoc:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

No diretório base do projeto, executamos o comando para gerar nossos Javadocs para um diretório em target \ site:

[email protected]:~$ mvn javadoc:javadoc

O plugin do Maven é muito poderoso e facilita a geração de documentos complexos sem problemas.

Vamos agora ver como é uma página Javadoc gerada:

link:/wp-content/uploads/2018/01/overview.png [imagem:/wp-content/uploads/2018/01/overview.png [imagem]]

Podemos ver uma visualização em árvore das classes que nossa classe SuperHero se estende. Podemos ver nossa descrição, campos e método, e podemos clicar nos links para obter mais informações.

Uma visão detalhada de nosso método se parece com isso:

link:/wp-content/uploads/2018/01/ss_javadoc-1024x579.png [imagem:/wp-content/uploads/2018/01/ss_javadoc-1024x579-1024x579.png [imagem]]

3.3 Tags Javadoc personalizadas

Além de usar tags de bloco predefinidas para formatar nossa documentação, também podemos criar tags de bloco personalizadas.

Para fazer isso, basta incluir uma opção -tag em nossa linha de comando Javadoc no formato _ <nome da etiqueta>: <nome da localização>: <cabeçalho> _.

Para criar uma tag personalizada chamada _ @ location_ permitida em qualquer lugar, exibida no cabeçalho "Notable Locations" em nosso documento gerado, precisamos executar:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

Para usar essa tag, podemos adicioná-la à seção de bloco de um comentário do Javadoc:

/**
 *This is an example...
* @location New York
 *@returns blah blah
*/

O plug-in Maven Javadoc é flexível o suficiente para permitir também definições de nossas tags personalizadas em nosso pom.xml.

Para configurar a mesma tag acima para o nosso projeto, podemos adicionar o seguinte à seção _ <tags> _ do nosso plugin:

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag>
</tags>
...

Dessa forma, podemos especificar a tag personalizada uma vez, em vez de especificá-la sempre.

4. Conclusão

Este tutorial de introdução rápida abordou como escrever Javadocs básicos e gerá-los com a linha de comando Javadoc.

Uma maneira mais fácil de gerar a documentação seria usar qualquer opção IDE embutida ou incluir o plug-in Maven em nosso arquivo pom.xml e executar os comandos apropriados.

Os exemplos de código, como sempre, podem ser encontrados over no GitHub.

Related