Java - Comentários da Documentação
A linguagem Java suporta três tipos de comentários -
| Nº Sr. | Comentário e descrição |
|---|---|
| 1 | /* texto */ O compilador ignora tudo de /* a */. |
| 2 | //texto O compilador ignora tudo, desde // até o final da linha. |
| 3 | /** documentação */ Este é um comentário de documentação e, em geral, é chamado de comentário de documento . O javadoc JDK ferramenta usa comentários de documentos ao preparar a documentação gerada automaticamente. |
Este capítulo trata da explicação do Javadoc. Veremos como podemos fazer uso do Javadoc para gerar documentação útil para o código Java.
O que é Javadoc?
Javadoc é uma ferramenta que vem com JDK e é usada para gerar documentação de código Java em formato HTML a partir de código-fonte Java, que requer documentação em um formato pré-definido.
A seguir está um exemplo simples em que as linhas dentro de /*….*/ são comentários de várias linhas Java. Da mesma forma, a linha que precede // é um comentário de linha única em Java.
Exemplo
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
Você pode incluir as tags HTML necessárias dentro da parte da descrição. Por exemplo, o exemplo a seguir usa
....
para cabeçalho e
foi usado para criar quebra de parágrafo −
Exemplo
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
As tags javadoc
A ferramenta javadoc reconhece as seguintes tags -
| Etiqueta | Descrição | Sintaxe |
|---|---|---|
| @autor | Adiciona o autor de uma classe. | @nome-texto do autor |
| {@code} | Exibe texto em fonte de código sem interpretar o texto como marcação HTML ou tags javadoc aninhadas. | {@code text} |
| {@docRoot} | Representa o caminho relativo para o diretório raiz do documento gerado de qualquer página gerada. | {@docRoot} |
| @deprecated | Adiciona um comentário indicando que esta API não deve mais ser usada. | @deprecated texto obsoleto |
| @exceção | Adiciona um Lançamentos subtítulo da documentação gerada, com o nome da classe e o texto descritivo. | @exception class-name descrição |
| {@inheritDoc} | Herda um comentário do mais próximo classe herdável ou interface implementável. | Herda um comentário da superclasse imediata. |
| {@link} | Insere um link em linha com o rótulo de texto visível que aponta para a documentação do pacote, classe ou nome de membro especificado de uma classe referenciada. | {@link package.class#member label} |
| {@linkplain} | Idêntico a {@link}, exceto que o rótulo do link é exibido em texto simples em vez de fonte de código. | {@linkplain package.class#member label} |
| @param | Adiciona um parâmetro com o nome de parâmetro especificado seguido pela descrição especificada na seção "Parâmetros". | @param descrição do nome do parâmetro |
| @return | Adiciona uma seção "Devoluções" com o texto da descrição. | @return descrição |
| @ver | Adiciona um título "Ver também" com um link ou entrada de texto que aponta para referência. | @ver referência |
| @serial | Usado no comentário do documento para um campo serializável padrão. | @serial field-description | incluir | excluir |
| @serialData | Documenta os dados escritos pelos métodos writeObject( ) ou writeExternal( ). | @serialData data-description |
| @serialField | Documenta um componente ObjectStreamField. | @serialField nome do campo tipo de campo descrição do campo |
| @desde | Adiciona um cabeçalho "Desde" com o texto especificado desde a documentação gerada. | @desde o lançamento |
| @throws | As tags @throws e @exception são sinônimos. | @throws descrição do nome da classe |
| {@value} | Quando {@value} é usado no comentário do documento de um campo estático, ele exibe o valor dessa constante. | {@value package.class#field} |
| @versão | Adiciona um subtítulo "Versão" com o texto da versão especificado aos documentos gerados quando a opção -versão é usada. | @versão versão-texto |
Exemplo
O programa a seguir usa algumas das tags importantes disponíveis para comentários de documentação. Você pode fazer uso de outras tags com base em suas necessidades.
A documentação sobre a classe AddNum será produzida no arquivo HTML AddNum.html mas ao mesmo tempo será criado um arquivo mestre com o nome index.html.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Zara Ali
* @version 1.0
* @since 2014-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
AddNum obj = new AddNum();
int sum = obj.addNum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}
Agora, processe o arquivo AddNum.java acima usando o utilitário javadoc da seguinte maneira -
$ javadoc AddNum.java Loading source file AddNum.java... Constructing Javadoc information... Standard Doclet version 1.7.0_51 Building tree for all the packages and classes... Generating /AddNum.html... AddNum.java:36: warning - @return tag cannot be used in method with void return type. Generating /package-frame.html... Generating /package-summary.html... Generating /package-tree.html... Generating /constant-values.html... Building index for all the packages and classes... Generating /overview-tree.html... Generating /index-all.html... Generating /deprecated-list.html... Building index for all classes... Generating /allclasses-frame.html... Generating /allclasses-noframe.html... Generating /index.html... Generating /help-doc.html... 1 warning $
Você pode conferir toda a documentação gerada aqui − AddNum. Se você estiver usando o JDK 1.7, o javadoc não gera um ótimo stylesheet.css , então sugerimos baixar e usar a folha de estilo padrão de https://docs.oracle.com/javase/7/docs/api/stylesheet.css
Java