English | 简体中文 | 繁體中文 | Русский язык | Français | Español | Português | Deutsch | 日本語 | 한국어 | Italiano | بالعربية
Java suporta três maneiras de comentário. Os dois primeiros são // E /* */Terceiro, chamado comentário explicativo, ele com /** Começar, com */Fim.
Comentários de descrição permitem que você insira informações sobre o programa no código. Você pode usar a ferramenta javadoc para gerar informações e exportá-las para arquivos HTML.
Comentários de descrição que permitem que você registre informações sobre seu programa de maneira mais conveniente.
A ferramenta javadoc reconhece as seguintes etiquetas:
| Etiqueta | Descrição | Exemplo |
|---|---|---|
| @author | Identifica o autor da classe. | @author description |
| @deprecated | Especifica uma classe ou membro descontinuado. | @deprecated description |
| {@docRoot} | Especifica o caminho do diretório raiz do documento atual. | Directory Path |
| @exception | Marca uma exceção lançada pela classe. | @exception exception-name explanation |
| {@inheritDoc} | Comentário herdado da superclasse imediata. | Herda um comentário da superclasse imediata. |
| {@link} | Insere um link para outro tópico. | {@link name text} |
| {@linkplain} | Insere um link para outro tópico, mas o link exibe uma fonte de texto puro. | Insere um in-line link to another topic. |
| @param | Descrição de um parâmetro de método. | @param parameter-name explanation |
| @return | Descrição do tipo de valor devolvido. | @return explanation |
| @see | Especifica um link para outro tópico. | @see anchor |
| @serial | Descrição de uma propriedade serializada. | @serial description |
| @serialData | Descrição dos dados escritos pelos métodos writeObject( ) e writeExternal( ). | @serialData description |
| @serialField | Descrição de um componente ObjectStreamField. | @serialField name type description |
| @since | Marca quando é introduzida uma mudança específica. | @since release |
| @throws | Igual à tag @exception. | A tag @throws tem o mesmo significado que a tag @exception. |
| {@value} | Exibe o valor da constante, que deve ser um atributo estático. | Exibe o valor de uma constante, que deve ser um campo estático. |
| @version | Especifica a versão da classe | @version info |
No início da /** depois, a primeira linha ou algumas linhas são descrições principais da classe, variável e método.
depois, você pode incluir uma ou mais variedades de @ etiquetas. Cada @ As etiquetas devem começar em uma nova linha ou imediatamente após um asterisco na linha inicial (*).
Múltiplas etiquetas do mesmo tipo devem ser agrupadas. Por exemplo, se você tiver três @see etiquetas, podem ser colocadas uma após a outra.
Abaixo está um exemplo de comentário de descrição da classe:
/*** Esta classe desenha um gráfico de barras * @author w3codebox * @version 1.2 */
A ferramenta javadoc usa o código-fonte do seu programa Java como entrada, gerando alguns arquivos HTML que contêm os comentários do seu programa.
As informações de cada classe estarão em arquivos HTML separados. O javadoc também pode gerar uma estrutura em árvore e índice de herança.
Devido às diferenças na implementação do javadoc, o trabalho pode variar. Você precisa verificar a versão do seu sistema de desenvolvimento Java e outros detalhes, escolhendo a versão apropriada do Javadoc.
Abaixo está um exemplo simples de comentário de instrução. Note que cada comentário está antes do item que descreve.
Após o processamento do javadoc, os comentários da classe SquareNum estarão no arquivo SquareNum.html.
import java.io.*;
/**
* Esta classe demonstra os comentários de documentação
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
/**
* Este método retorna o quadrado de num.
* Esta é uma descrição multilinha. Você pode usar
* quantas linhas quiser.
* @param num O valor a ser quadrado.
* @return O quadrado de num.
*/
public double square(double num) {
return num * num;
}
/**
* Este método recebe um número do usuário.
* @return O valor de entrada como um double.
* @exception IOException Em erro de entrada.
* @see IOException
*/
public double getNumber() throws IOException {}}
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* Este método demonstra square().
* @param args Não usado.
* @return Nada.
* @exception IOException Em erro de entrada.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
SquareNum ob = new SquareNum();
double val;
System.out.println("Digite o valor a ser quadrado: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("O valor quadrado é " + val);
}
}Aqui está, usando a ferramenta javadoc para processar o arquivo SquareNum.java:
$ javadoc SquareNum.java Carregando arquivo de código-fonte SquareNum.java... Construindo informações do Javadoc... Versão padrão do Doclet 1.5.0_13 Construindo árvore para todos os pacotes e classes... Gerando SquareNum.html... SquareNum.java:39: aviso - @return etiqueta não pode ser usada\ método com tipo de retorno void. Gerando pacote-frame.html... Gerando pacote-Resumo.html... Gerando pacote-tree.html... Gerando constante-values.html... Construindo índice para todos os pacotes e classes... Gerando visão geral-tree.html... Gerando índice-all.html... Gerando deprecated-list.html... Construindo índice para todas as classes... Gerando allclasses-frame.html... Gerando allclasses-noframe.html... Gerando index.html... Gerando ajuda-doc.html... Gerando stylesheet.css... 1 aviso $