Documentando con
Javadoc
1
Problema
➔
Como saber quais classes podemos usar?
Quais os seus métodos e o que eles fazem?
Através de alguma documentação.
➔
A documentação do Java pode ser acessada
via Internet a partir do endereço:
http://java.sun.com/javase/6/docs/api/
➔
2
Javadoc:
Quadro superior esquerdo: pacotes
Quadro inferior esquerdo: classes e interfaces.
Quadro da direita: detalhes do que foi escolhido.
Métodos e atributos privados não aparecem.
Podemos gerar nossos próprios javadoc a partir da
linha de comando, usando o comando javadoc.
Geração de Javadoc
➔
A partir do Eclipse
Menu Project > Generate Javadoc
Ou pelo export do projeto.
3
Javadoc
O Javadoc é criado a partir de comentários delimitados
por /** e */.
Linhas entre os delimitadores apenas precisam de um
*.
Nos comentários podemos definir autor, versão,
parâmetros, retorno, etc.
/**
* Classe responsavel por moldar as Contas do Banco
*
* @author Guilherme
*
*/
public abstract class Conta {
4
Javadoc
/**
* Metodo que incrementa o saldo.
*
* @param valor
*/
public void deposita(double valor) {
5
Javadoc
6
Comentários em Java
Comentários de linha
Iniciam com duas barras consecutivas (//) e
continuam até o final da linha
Comentários em bloco
Iniciam com a seqüência barra asterisco (/*) e
encerram com a seqüência inversa asterisco
barra (*/)
Podem se estender por mais de uma linha
Comumente usa-se um asterisco no início de
cada linha que compõe o comentário
7
Comentários em Java
//Exemplo de comentário de linha
//Outra linha de comentário
/* Exemplo de comentário
* em bloco que se estende por mais
* de uma linha
*/
/* Outro exemplo de comentário
em bloco */
8
Documentação com Javadoc
➔
Sintaxe
Possui um conjunto doc tags que são comandos
iniciados por @ e divididas em dois subconjuntos:
Standalone doc tags devem estar no início de cada
linha
In line doc tags podem aparecer em qualquer parte do
javadoc e devem vir entre chaves {...}
Aceita HTML embutido.
9
Documentação
10
/**
* Classe base responsável pelo armazenamento das
* informações do cliente da loja.
* @autor Fulano
* @version 1.0
*/
public class Pessoa {
/**
* Identidicador único do Cliente no sistema
*/
private int id;
...
/**
* Construtor ...
*/
public Pessoa() {
...
}
/**
* Fornece o identificador único do cliente
* @return Número que identifica o clienete no sistema
*/
public int getId(){
return id;
}
// ...
}
HTML embutido
javadoc passa todo código HTML contido no
comentário para o HTML gerado
Usado para formatar o comentário
Exemplo:
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
/**
* Você pode
* <ol>
* <li> Item
* <li> Item
* <li> Item
* </ol>
*/
11
<b>inserir</b> listas:
um
dois
três
doc tags
@see – faz referência à documentação de outra
classe
@see nome-da-classe
@see nome-completamente-qualificado
@see nome-completamente-qualificado#nome-metodo
Gera o link “See Also” na documentação
{@link} – semelhante à tag see, exceto pelo fato de
poder ser usada inline e permitir a adição de um
rótulo
{@link nome-completamente-qualificado#nome-metodo
rotulo}
{@docRoot} - fornece um path relativo para o
diretório raiz da documentação gerada
/**
* Veja o <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
12
doc tags
{@inheritDoc} – herda o comentário de uma
superclasse dentro do comentário corrente
/**
* Insere as informações no Banco de Dados. {@inheritDoc}
*/
public void save(Pessoa pessoa)
@version – informação sobre a versão da classe
/**
* Classe responsável pela persistência das informações.
*
* @version 1.2
*/
public class PessoaBD{ ... }
13
doc tags
@author – informação sobre o autor da classe
/**
* Classe responsável pela persistência das informações.
*
* @author Fulano da Silva
* @author Beltrano da Silva
*/
public class PessoaBD{...}
@since – permite informar a versão do código a partir
da qual um característica e suportada
/**
* Insere as informações no Banco de Dados.
*
* @since 1.2
*/
public void save(Pessoa pessoa)
14
doc tags
@param – usada na documentação de métodos.
Permite fazer uma descrição da lista de parâmetros
de um método
/**
* Insere as informações no Banco de Dados.
*
* @param pessoa Objeto que contém as informações
* @param usuario Usuario responsável pela operação
* @since 1.2
*/
public void insert(Pessoa pessoa, Usuario usuario)
@return – usada na documentação de métodos.
Permite fazer uma descrição do retorno do método
/**
* Lista todos as pessoas cadastradas
*
* @return Uma lista formada por todas as pessoas cadastradas
*/
public List findAll(){...}
15
doc tags
@deprecated – indica que o elemento relacionado
será substituído por outro melhorado
/**
* Insere as informações no Banco de Dados.
*
* @param pessoa Objeto que comtém as informações
* @deprecated
*/
public void insert(Pessoa pessoa)
16
Parte integrante do JDK
➔
Sinopse:
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ @argfiles ]
options: Opções de linha de comando
packagenames: lista de nomes de pacotes, separados por
espaço, que deverão ser documentados
sourcefilenames: lista de nomes de arquivos, separados por
espaço. Javadoc processará todos os arquivos terminados
com .java
@argfiles: um ou mais arquivos que contém opções
Javadoc, lista de pacotes ou lista de arquivos fontes em
qualquer ordem
17