Java - comentários de documentação
A linguagem Java suporta três tipos de comentários -
| Sr. Não. | Comentário e descrição |
|---|---|
| 1 | /* text */ O compilador ignora tudo de / * a * /. |
| 2 | //text O compilador ignora tudo desde // até o final da linha. |
| 3 | /** documentation */ Este é um comentário de documentação e em geral é chamado doc comment. oJDK javadocferramenta usa comentários de documentos ao preparar documentação gerada automaticamente. |
Este capítulo explica como explicar Javadoc. Veremos como podemos usar Javadoc para gerar documentação útil para o código Java.
O que é Javadoc?
Javadoc é uma ferramenta que acompanha o JDK e é utilizada para gerar documentação de código Java em formato HTML a partir do código-fonte Java, o que requer documentação em formato predefinido.
A seguir está um exemplo simples onde as linhas dentro de /*….*/ são comentários Java de várias linhas. Da mesma forma, a linha que precede // é o comentário de linha única do 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 tags HTML necessárias dentro da parte da descrição. Por exemplo, o exemplo a seguir faz uso de <h1> .... </h1> para título e <p> 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 -
| Tag | Descrição | Sintaxe |
|---|---|---|
| @autor | Adiciona o autor de uma classe. | @author name-text |
| {@código} | 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 a partir de qualquer página gerada. | {@docRoot} |
| @descontinuada | Adiciona um comentário indicando que esta API não deve mais ser usada. | @deprecated deprecatedtext |
| @exceção | Adiciona um Throws subtítulo da documentação gerada, com o nome da classe e o texto de descrição. | @exception class-name description |
| {@inheritDoc} | Herda um comentário do nearest classe herdável ou interface implementável. | Herda um comentário da classe superior imediata. |
| {@ligação} | 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 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 do que a fonte do código. | {@linkplain package.class # member label} |
| @param | Adiciona um parâmetro com o nome do parâmetro especificado seguido pela descrição especificada à seção "Parâmetros". | @param parameter-name description |
| @Retorna | Adiciona uma seção "Devoluções" com o texto da descrição. | @return description |
| @Vejo | Adiciona um título "Consulte também" com um link ou entrada de texto que aponta para a 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 gravados pelos métodos writeObject () ou writeExternal (). | @serialData data-description |
| @serialField | Documenta um componente ObjectStreamField. | @serialField field-name field-type field-description |
| @Desde a | Adiciona um título "Desde" com o texto desde especificado à documentação gerada. | @since lançamento |
| @throws | As tags @throws e @exception são sinônimos. | @throws class-name description |
| {@valor} | Quando {@value} é usado no comentário de 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 -version é usada. | @version version-text |
Exemplo
O programa a seguir usa algumas das tags importantes disponíveis para comentários de documentação. Você pode usar outras tags com base em seus requisitos.
A documentação sobre a classe AddNum será produzida no arquivo HTML AddNum.html, mas ao mesmo tempo um arquivo mestre com um nome index.html também será criado.
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 verificar toda a documentação gerada aqui - AddNum . Se você estiver usando o JDK 1.7, o javadoc não gera um grandestylesheet.css, então sugerimos baixar e usar a folha de estilo padrão do https://docs.oracle.com/javase/7/docs/api/stylesheet.css