O Javadoc é uma ferramenta que permite extrair a
documentação directamente a partir dos ficheiros de
código.
Esta abordagem tem a vantagem de, ao contrário do que é usual, a documentação não ter de ser mantida em ficheiros independentes dos do código, o que, normalmente, acarreta dificuldades de sincronização entre as versões do código e as versões da documentação.
Assim, de cada vez que alguma parte do código é modificada, basta actualizar os comentários correspondentes, que a ferramenta se responsabiliza por gerar a nova documentação.
Além disso, uma vez que a documentação é
produzida em formato HTML, a navegação nas
páginas do manual é facilitada, bem como a sua eventual
disponibilização na Internet.
Um programa deve ser escrito para ser lido por pessoas e eventualmente ser interpretado por um computador. Este factor torna-se ainda mais crítico quando se trabalha em equipa e um programador tem de usar módulos criados por outro programadores.
Assim sendo, é essencial que um programa esteja bem documentado, pois esta é a principal fonte de informação de que um programador dispõe quando quer (re) utilizar código.
Os comentários no código fonte Java que
constituem a documentação devem ser delimitados por
/** ... */ para serem reconhecidos pelo Javadoc.
Tipicamente:
/** * Formatação usual de um comentário. **/
Para poupar espaço e no comentário de variáveis, pode juntar-se tudo na mesma linha:
/** Este comentário só ocupa uma linha. */
Comentários nesse formato são reconhecidos e processados pelo
Javadoc para gerar a API (Application Programming Interface) da
classe.
O Javadoc produz a documentação a partir do
código fonte das classes Java (ficheiros .java);
dos ficheiros com os comentários relativos aos pacotes
(ficheiro package.html na directoria de cada pacote) e
dos vários ficheiros que forem referidos (incluindo imagens,
excertos de código, ficheiros de classe, ficheiros HTML e tudo
aquilo que possa ser referenciado nos ficheiros anteriores).
Sempre que se escrever mais do que uma frase descritiva num comentário, a primeira é única a ser apresentada nas tabelas de resumos iniciais, pelo que deve ser suficientemente explicativa, ao mesmo tempo que deve ser sumária. Tipicamente, nessa frase descreve-se num nível de abstracção elevado o que representa, o que significado e/ou a funcionalidade, deixando-se para as frases seguintes, a explicação detalhada do funcionamento ou exemplos de utilização.
Os comentários são escritos em HTML, utilizando as marcas e os símbolos habituais. Por exemplo:
/** * Este é um <b>comentário</b> HTML com acentos. * E este e um comentario em HTML sem acentos - tambem para exemplificacao. **/
Quando o Javadoc processa um ficheiro, os asteriscos
(*) iniciais de cada linha são ignorados.
Será conveniente evitar declarações múltiplas uma vez que cada variável deve ter os seus próprios comentários:
/** * Coordenadas de um ponto **/ public int x, y; // evitar
Também se deve evitar a utilização das marcas
<H1>, <H2>, etc, do HTML uma vez que o Javadoc cria a
sua própria estrutura hierárquica.
Como ferramenta genérica que é o Javadoc
disponibiliza algumas marcas úteis:
@author |
Necessário nas classes e interfaces, opcional nos métodos e constructores: indica os autores do código da classe, ou de um determinado método. |
@version |
Necessário nas classes e interfaces, opcional nos métodos e constructores. |
@param |
Apenas para métodos e construtores: indica o nome dos argumentos de um método ou construtor e o respectivo significado. |
@return |
Apenas para métodos: indica o significado daquilo que é devolvido. |
@throws |
sempre que houver excepções deve explicar-se porque é que ocorrem e como são tratadas. |
@see |
para referências relevantes: cria ligações entre
os documentos HTML produzidos pelo Javadoc |
@since |
versão a partir da qual passou a estar disponível |
As marcas devem ser omitidas sempre que não forem necessárias.
Por exemplo, num método sem argumentos, omite-se o @param.
O comentário relativo a uma classe deve aparecer depois de todas as
declarações de dependências (import), caso
contrário o Javadoc não as interpretará
correctamente.
O Javadoc permite interligar os comentários das
várias classes através da marca @see. Seguem-se
exemplificações de referências:
Referência a membros da classe que se está a comentar
@see #variavelDaClasseActual
@see #ConstrutorDaClasseActual(Type, Type...)
@see #ConstrutorDaClasseActual(Type id, Type id...)
@see #metodoDaClasseActual(Type, Type,...)
@see #metodoDaClasseActual(Type id, Type, id...)
Referência a membros da classe do mesmo pacote ou de pacotes importados
@see OutraClasse
@see OutraClasse#variavel
@see OutraClasse#Construtor(Type, Type...)
@see OutraClasse#Construtor(Type id, Type id)
@see OutraClasse#metodo(Type, Type,...)
@see OutraClasse#metodo(Type id, Type id,...)
Referência a outros pacotes
@see outroPacote
@see outroPacote.OutraClasse
@see outroPacote.OutraClasse#variavel
@see outroPacote.OutraClasse#Construtor(Type, Type...)
@see outroPacote.OutraClasse#Construtor(Type id, Type id)
@see outroPacote.OutraClasse#metodo(Type, Type,...)
@see outroPacote.OutraClasse#metodo(Type id, Type, id)
O Javadoc substitui os @see referência
descrição da referência pela
descrição transformando o texto numa
ligação HTML à referência.
Além das marcas anteriormente descritas, o Javadoc
permite ainda a introdução de ligações
HTML. Para isso, utiliza-se a tag: {@link
morada etiqueta} que introduz
uma ligação para a morada indicada com a etiqueta dada.
Não há limites para o número de
ligações.
Por exemplo, uma ligação para o método
metodo() da class Class1 escrever-se-ia da
seguinte forma:
Use o {@link #metodo() metodo}.
O que produziria o seguinte HTML:
Use o <a href="Class1.html#metodo()">metodo</a>.
O que apareceria na página gerada como:
Use o metodo.
Esta marca funciona como o @see. No entanto, enquanto um
@see produz uma secção onde todas as
ligações são estão agrupadas; um @link
produz a mesma referência mas coloca-a no meio do texto.
Para se referirem documentos externos, utiliza-se a marca HTML
de referências: <a href="morada">etiqueta</a>.
O Javadoc inclui na documentação os
cabeçalhos dos métodos, os tipos das variáveis,
dos argumentos e dos resultados, pelo que é conveniente que os
comentários acrescentem informação relevante.
Por exemplo, se tivermos o seguinte comentário para o
método modificaTextoMenu não obtemos
nenhuma informação relevante:
/**
* modifica o texto do menu
* @param texto texto do menu
**/
public modificaTextoMenu(String texto) { /* codigo */ }
Pelo contrário, um comentário que remeta para o significado e utilização do método é bem mais informativo:
/**
* regista o texto que deve ser apresentado quando se apresentar o menu.
* o texto é apresentado sempre que o menu for mostrado ao utilizador.
* @param texto String a ser apresentada ao utilizador para identificar o
* menu em questão. Se for uma String vazia, não
* mostrada nenhuma informação.
**/
public modificaTextoMenu(String texto) { /* codigo */ }
A partir da versão 1.2, o Javadoc passou permitir
comentários ao nível dos pacotes (como é o caso deste
documento).
Para isso, cada pacote pode ter os seus próprios comentários
que o Javadoc depois se encarrega de adicionar à primeira página
da documentação HTML produzida para o pacote.
Esses comentários devem estar no ficheiro package.html.
É o mesmo nome de ficheiro para todos os pacotes, uma vez que o
código relativo a cada pacote está, por definição,
arrumado em directorias diferentes (com o nome do pacote).
Assim, esse ficheiro deve ser guardado juntamente com os ficheiros fonte
(*.java) na directoria onde estiver o código das classes
do pacote a documentar.
Note-se que só se considera aquilo que se encontra no corpo do
documento HTML, ou seja, aquilo que se encontra entre
<body> e </body>. Para se definirem
títulos, cabeçalhos, rodapés ou notas de rodapé,
devem ser definidas utilizando as opções correspondentes
(consultar o manual relativo a -windowtitle, doctitle,
-header, -footer e -bottom)
Sempre que se escreve código Java é conveniente
acompanhar a produção e escrita do código da sua correcta
documentação. Caso contrário, se deixamos essa tarefa
para uma fase posterior, perdemos as vantagens da utilização
da ferramenta - cuja intenção é, como se disse, juntar
o momento da escrita do código ao momento da sua
documentação.
Uma vez escrito e documentado o texto, será necessário
utilizar o Javadoc para produzir a documentação
no formato esperado para que possa ser consultada.
Para isso deve utilizar-se o comando Javadoc disponível
em qualquer instalação do JDK:
javadoc [ opções ] [ nomeDosPacotes ] [ ficheirosFonte ] [ @ficheiros ]
Os argumentos podem ser dados numa ordem qualquer.
É necessário especificar quais os pacotes que se quer
documentar.
O Javadoc procura os pacotes e as classes nos caminhos definidos
pela opção -sourcepath.
Não são permitidas expressões regulares como
asteriscos (*) nos nomes dos pacotes, mas são permitidas no nome
dos ficheiros com o código fonte (aqui é necessário
indicar a localização dos ficheiros uma vez que o
-sourcepath não é utilizado).
@ficheiros indica um ou mais ficheiros que contenham uma lista de
pacotes e ficheiros fonte, um por linha.
Os ficheiros gerados podem ser visualizados com ou sem frames html:
index.html (com frames)overview-summary.html (sem frames)No caso de se utilizarem frames, a disposição é a seguinte:
------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt
Onde C é o índice relativo a uma classe,
P é o índice relativo a um pacote e o
Detail é a documentação que se escolhe
ver em cada momento (e que muda com a navegação nos documentos.
javadoc
listando todas as opções disponíveis.
.java) quando se procuram os pacotes dados ao comando
javadoc. Se for omitido, utiliza o classpath
para procurar os ficheiros fonte. Se o classpath
(definido com a opção -classpaht) também
for omitido, utiliza a directoria actual (e as suas subdirectorias) para
procurar os ficheiros.
Por exemplo, suponha que se vai documentar o pacote
meusPacotes.pacoteTeste cujos ficheiros fonte estejam em
~/PO/javadoc-sample/meusPacotes/pacoteTeste/*.javaNesse caso, o
sourcepath a utilizar seria
~/PO/javadoc-sample que na directoria
meusPacotes/pacoteTeste contém os ficheiros fonte do
pacoteTeste:
javadoc -sourcepath ~/PO/javadoc-sample meusPacotes.pacoteTesteTorna-se simples recordar o nome do pacote se se reparar que corresponde a trocar os pontos ("
.") por barras ("/") o que
corresponde a dizer que o caminho completo para os ficheiros fonte é:
~/PO/javadoc-sample/meusPacotes/pacoteTeste
Javadoc deve guardar
os ficheiros HTML produzidos. Se esta opção for
omitida os ficheiros são guardados na directoria corrente.
@version, que por omissão são omitidos.
@author nos
documentos gerados, que por omissão são omitidos.
O arquivo IntroJavadoc-apoio.jar anexo a este documento exemplifica a utilização do Javadoc na produção automática de documentação de ficheiros fonte Java.
É definido o pacote meusPacotes que contém
os pacotes pacoteTeste e outroPacote. Cada
um desses pacotes contém algumas classes escritas para
exemplificar a utilização do Javadoc. Para gerar a
documentação referente a estes pacotes deve executar o
comando (para gerar a documentação relativa a todas as
classes e membros dos pacotes e colocar os ficheiros produzidos na
directoriaDeOutput):
javadoc -d directoriaDeOutput meusPacotes.pacoteTeste meusPacotes.outroPacote meusPacotes -private