Javadoc - Javadoc
Javadoc (originalmente cased JavaDoc ) é um gerador de documentação criado pela Sun Microsystems para a linguagem Java (agora de propriedade da Oracle Corporation ) para gerar documentação API em formato HTML a partir do código-fonte Java . O formato HTML é usado para adicionar a conveniência de ser capaz de criar links para documentos relacionados.
O formato de "comentários de documentos" usado por Javadoc é o padrão de mercado de fato para documentar classes Java. Alguns IDEs , como IntelliJ IDEA , NetBeans e Eclipse , geram HTML Javadoc automaticamente. Muitos editores de arquivo auxiliam o usuário na produção do código-fonte Javadoc e usam as informações do Javadoc como referências internas para o programador.
Javadoc também fornece uma API para a criação de doclets e taglets, que permite aos usuários analisar a estrutura de um aplicativo Java. É assim que o JDiff pode gerar relatórios do que mudou entre duas versões de uma API.
Javadoc não afeta o desempenho em Java, pois todos os comentários são removidos no momento da compilação. Escrever comentários e Javadoc é para entender melhor o código e assim mantê-lo melhor.
História
Javadoc foi um dos primeiros geradores de documentação da linguagem Java . Antes do uso de geradores de documentação, era comum usar escritores técnicos que normalmente escreveriam apenas documentação independente para o software, mas era muito mais difícil manter essa documentação sincronizada com o próprio software.
Javadoc tem sido usado por Java desde a primeira versão e geralmente é atualizado a cada nova versão do Java Development Kit .
A @field
sintaxe do Javadoc foi emulada por sistemas de documentação para outras linguagens, incluindo a linguagem cruzada Doxygen , o sistema JSDoc para JavaScript e o HeaderDoc da Apple .
Arquitetura técnica
Estrutura de um comentário Javadoc
Um comentário Javadoc é desencadeado no código por tags de comentário de várias linhas padrão /*
e */
. A tag de abertura (chamada de delimitador de comentário inicial) tem um asterisco extra, como em /**
.
- O primeiro parágrafo é uma descrição do método documentado.
- Após a descrição, há um número variável de tags descritivas, significando:
- Os parâmetros do método (
@param
) - O que o método retorna (
@return
) - Quaisquer exceções que o método pode lançar (
@throws
) - Outras tags menos comuns, como
@see
(uma tag "veja também")
- Os parâmetros do método (
Visão geral do Javadoc
A estrutura básica para escrever comentários de documentos é incorporá-los
/** ... */
. O bloco de comentário Javadoc é posicionado imediatamente acima dos itens sem nenhuma nova linha de separação. Observe que qualquer instrução de importação deve preceder a declaração da classe. A declaração da classe geralmente contém:
// import statements
/**
* @author Firstname Lastname <address @ example.com>
* @version 1.6 (current version number of program)
* @since 1.2 (the version of the package this class was first added to)
*/
public class Test {
// class body
}
Para métodos, há (1) uma descrição curta e concisa de uma linha para explicar o que o item faz. Isso é seguido por (2) uma descrição mais longa que pode abranger vários parágrafos. Os detalhes podem ser explicados na íntegra aqui. Esta seção é opcional. Por último, há (3) uma seção de tag para listar os argumentos de entrada aceitos e os valores de retorno do método. Observe que todo o Javadoc é tratado como HTML, portanto, as várias seções de parágrafo são separadas por uma <p>
marca de quebra de parágrafo " ".
/**
* Short one line description. (1)
* <p>
* Longer description. If there were any, it would be (2)
* here.
* <p>
* And even more explanations to follow in consecutive
* paragraphs separated by HTML paragraph breaks.
*
* @param variable Description text text text. (3)
* @return Description text text text.
*/
public int methodName (...) {
// method body with a return statement
}
As variáveis são documentadas de forma semelhante aos métodos, com a exceção de que a parte (3) é omitida. Aqui, a variável contém apenas uma breve descrição:
/**
* Description of the variable here.
*/
private int debug = 0;
Observe que não é recomendado definir várias variáveis em um único comentário de documentação. Isso ocorre porque o Javadoc lê cada variável e as coloca separadamente na página HTML gerada com o mesmo comentário de documentação que é copiado para todos os campos.
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // AVOID
Em vez disso, é recomendável escrever e documentar cada variável separadamente:
/**
* The horizontal distance of point.
*/
public int x;
/**
* The vertical distance of point.
*/
public int y;
Tabela de tags Javadoc
Algumas das tags Javadoc disponíveis estão listadas na tabela abaixo:
Tag e parâmetro | Uso | Aplica-se a | Desde a |
---|---|---|---|
@author John Smith | Descreve um autor. | Classe, Interface, Enum | |
{ @docRoot } | Representa o caminho relativo para o diretório raiz do documento gerado a partir de qualquer página gerada. | Classe, Interface, Enum, Campo, Método | |
versão @version | Fornece entrada de versão de software. Máximo de um por classe ou interface. | Classe, Interface, Enum | |
@since since-text | Descreve quando essa funcionalidade existiu pela primeira vez. | Classe, Interface, Enum, Campo, Método | |
@ver referência | Fornece um link para outro elemento de documentação. | Classe, Interface, Enum, Campo, Método | |
@param nome descrição | Descreve um parâmetro de método. | Método | |
@return description | Descreve o valor de retorno. | Método | |
@exception classname description @throws classname description |
Descreve uma exceção que pode ser lançada a partir desse método. | Método | |
@ descrição obsoleta | Descreve um método desatualizado. | Classe, Interface, Enum, Campo, Método | |
{ @inheritDoc } | Copia a descrição do método substituído. | Método de Substituição | 1.4.0 |
{ @link reference } | Link para outro símbolo. | Classe, Interface, Enum, Campo, Método | |
{ @linkplain reference } | Idêntico a {@link}, exceto que o rótulo do link é exibido em texto simples do que a fonte do código. | Classe, Interface, Enum, Campo, Método | |
{ @value #STATIC_FIELD } | Retorna o valor de um campo estático. | Campo Estático | 1.4.0 |
{ @code literal } | Formata o texto literal na fonte do código. É equivalente a <code> {@literal} </code>. | Classe, Interface, Enum, Campo, Método | 1.5.0 |
{ @ literal literal } | Denota texto literal. O texto fechado é interpretado como não contendo marcação HTML ou tags javadoc aninhadas. | Classe, Interface, Enum, Campo, Método | 1.5.0 |
{ @serial literal } | Usado no comentário do documento para um campo serializável padrão. | Campo | |
{ @serialData literal } | Documenta os dados gravados pelos métodos writeObject () ou writeExternal (). | Campo, Método | |
{ @serialField literal } | Documenta um componente ObjectStreamField. | Campo |
Exemplos
Segue um exemplo de Javadoc para documentar um método. Observe que o espaçamento e o número de caracteres neste exemplo são como as convenções.
/**
* Validates a chess move.
*
* <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
*
* @param fromFile file from which a piece is being moved
* @param fromRank rank from which a piece is being moved
* @param toFile file to which a piece is being moved
* @param toRank rank to which a piece is being moved
* @return true if the move is valid, otherwise false
* @since 1.0
*/
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
Veja também
Referências
links externos
- Java Platform, Standard Edition Javadoc Guide
- Solicitação de especificação Java de atualização de tecnologia de tag Javadoc JSR 260 (define novas tags Javadoc)
- Melhore em Javadoc com ashkelon
- Globaldocs: um visualizador para navegar em vários Javadocs simultaneamente.
- Várias documentações Java convertidas para o formato de Ajuda do Windows