Universidade Federal Rural da Amazônia

Instituto Ciberespacial
Bacharelado em Informática Agrária
Professor João Santanna

JavaDoc – Implementando documentação através do NetBeans

1. Introdução
Documentar pontos estratégicos de nossos códigos fontes, é uma
necessidade universal em vários paradigmas ou plataformas de
desenvolvimento. E cada vez mais, precisamos gerar e manipular de uma
forma eficiente todos os comentários em formato de documentação de
códigos, visando com isso, facilitar a reutilização futura desses comentários
como fonte geradora de conhecimentos acerca de uma classe.
Em Java, felizmente, temos um recurso do próprio JDK, que facilita todo o
trabalho de criação e manipulação dos comentários, essa ferramenta não
poderia ter um nome mais sugestivo, estamos falando do JavaDoc.
De maneira geral o JavaDoc fornece uma linguagem especifica para
enriquecer os comentários que introduzem classes, atributos e métodos.
Seu funcionamento baseia-se na inserção de textos explicativos em forma de
um comentário especial, que antecedem um escopo de uma classe ou
método, tendo assim, a responsabilidade de apresentar o mesmo.
Seu funcionamento é através do uso de marcação de documentos com
doclets, gerando arquivos nos formatos HTML, SGML, XML ou RTF. Tais
marcações são feitas através de comentários, contendo tags especiais que
especificam quais informações serão inseridas, com objetivo de manter uma
massa de conhecimento reutilizável em qualquer projeto que faça uso da
classe em questão.
Vale ressaltar, que podemos combinar tags da própria especificação HTML,
com as tags oferecidas pelo JavaDoc, tornando possível à criação de
documentos completos gerados a partir dos comentários do próprio código.

2. Entendendo a sintaxe
A estrutura básica de um comentário de documentação tem como
característica principal, o uso de uma barra e dois asteriscos( /** ) no início e
no seu final, possui um asterisco e uma barra ( */ ). Veja as listagens 01 e 02.

 
  

/** Exemplo básico de um comentário em JavaDoc */

Listagem 01 - Uma linha.

/** Exemplo básico de um comentário em JavaDoc

* com mais de uma linha.
*/
Listagem 02 - Várias linhas.

Por convenção, sugere-se alocar os blocos de comentários, antes da

definição de uma classe, interface, atributos, ou métodos, dessa forma,
criamos uma introdução conceitual ao referido elemento do código.
3. Entendendo as tags
Um ponto forte do JavaDoc é o uso de tags especiais a fim de qualificar
melhor a informação contida nos comentários.
Com as tags podemos especificar, por exemplo, o autor, a versão, links, data,
exceções lançadas, lista de argumentos de um método e tipo de retorno de
um método.
Essas tags são inseridas dentro do bloco de comentários, antecedidas pelo
carctetre @ (arroba), e após o nome da própria tag, inseri-se o conteúdo
desejado. Veja na tabela 01, as tags disponíveis:

Tag Significado
@author Especifica o autor da classe ou do método em questão.
@deprecated Identifica classes ou métodos obsoletos. É interessante
informar nessa tag, quais métodos ou classes podem ser
usadas como alternativa ao método obsoleto.
@link Possibilita a definição de um link para um outro documento
local ou remoto através de um URL.
@param Mostra um parâmetro que será passado a um método.
@return Mostra qual o tipo de retorno de um método.
@see Possibilita a definição referências de classes ou métodos, que
podem ser consultadas para melhor compreender idéia
daquilo que está sendo comentada.
@since Indica desde quando uma classe ou métodos foi adicionado na
aplicação.
@throws Indica os tipos de exceções que podem ser lançadas por um
método.
@version Informa a versão da classe.
Tabela 01 - Tags oferecidas pelo JavaDoc.

 
  

Exemplos
Vamos olhar agora alguns exemplos de codificação com o uso de
comentários JavaDoc.
Comentário simples : Primeiro mostrarei um exemplo simples de um
comentário, veja a listagem 03.

/** Um exemplo de um simples de comentário com o JavaDoc */

Listagem 03

Outro exemplo interessante é a inserssão de tags HTML dentro do próprio

comentário javadoc , vamos ver esse exemplo na listagem 04 que mostra o
uso de tags <b> e <i> para negritar e colocar em itálico trechos de nossos
comentários.

/** Com esta combinação podemos inserir <b>marcações </b> HTML em <i>
nossos </i> comentarios */
Listagem 04

4. Comentários em classes
Veja agora na listagem 05, um exemplo de classe com atributos e métodos
comentados com JavaDoc.
package projetojavadoc;
/**Classe para objetos do tipo Funcionários, onde serão contidos, valores e métodos para o
mesmo.
* @author Manoel Pimentel
* @version 1.05
* @since Release 02 da aplicação
*/

public class Funcionarios {

private String matricula;
private Double salario;

/** Método para retorno da matrícula do funcionário

* @return String - Nr da Matrícula*/
public String getMatricula( ){
return this.matricula;
}

/** Método para retorno do salário do funcionário

* @return Double - Valor do Salário */

public Double getSalario( ){

return this.salario;
}

/**Método para calculo da diária com base no salário do

* funcionário dividido pelo mês comercial de 30 dias para efeito * de cálculo de ajuda de

 
  

custo para viagem.

* @author Emanuel Silva
* @param diasViagem int - Valor total das vendas do mês.
* @param valorDeslocamento Double - Valor pago em cada diária despesas básicas de
deslocamento.
* @return Double - Valor da diaria
*/
public Double calculaAjudaCusto(int diasViagem, Double valorDeslocamento) throws
ArithmeticException {
try{
return (this.salario / 30)*diasViagem+valorDeslocamento;
}catch (ArithmeticException ae){
return 0.0;
}
}

/**Método para calculo do valor da bonificação baseada na

* seguinte faixa de valores: Para vendas menores de
* 25.000,00, o percentual de comissão aplicado será de 5%, e * para valores iguais ou
maiores de 25.000,00, o percentual
* será de 10%
* @author Manoel Pimentel
* @param valorVendas - Valor total das vendas do mês
* @return Double - Valor do resultado do cálculo conforme a faixa de comissões.
*/
public Double calculaBonificacao(Double valorVendas) {
if (valorVendas <25000.00 ){
return this.salario * 0.05;
} else {
return this.salario * 0.10;
}
}

}
Listagem 05 – Código da classe exemplo Funcionarios.java

5. Automatizando através do NetBeans

O NetBeans que atualmente encontra-se na versão 6.8, oferece recursos
nativos na própria IDE para:
- Seja criados de maneira automática os comentários no mesmo momento da
criação de uma classe em projeto.
- Code completion para mostrar as tags JavaDoc disponíveis em cada área
do código.
- Gerador para a criação de documentos HTML, contendo a documentação
feita através dos comentários em JavaDoc.

Neste artigo, pressuponho que você já possua alguma familiaridade com

programação em Java através do NetBeans, mas caso contrário, acesse

 
  

www.netbeans.org e adquira maiores informações de como instalar e usar a

IDE.

5.1 Criando um projeto no NetBeans

Vamos agora criar um projeto básico, para isso, abra o NetBeans, clique no
menu File/New, será aberta uma janela para escolher o tipo de projeto
desejado, nessa etapa, escolha Java Application, siga os procedimentos para
nomeação e definição dos diretórios onde será armazenado esse nosso
projeto.
Após a conclusão desse processo, se você deixou marcado a opção Create a
main class na tela de construção da aplicação, seu projeto terá uma classe
chamada Main, que dentre outras finalidades, possui um método main para o
bloco de execução principal de sua aplicação. Note que essa classe já foi
criada com alguns comentários usando JavaDoc
Para ter a total visão sobre a aplicação do JavaDoc, crie no próprio
NetBeans, uma classe chamada Funcionarios, e codifique-a conforme a
listagem 05 mostrada anteriormente.
É importante você notar que o NetBeans possui um recurso de code
completion para mostrar e inserir as tags disponíveis, ou seja, dentro do
bloco de comentário, você pode digitar o sinal de @ (arroba) seguido pelo
pelas teclas Ctrl+Espaço, para que seja mostrada uma pequena janela
flutuante estilo menu popup sobre seu código, para que seja escolhida a tag
desejada.
Uma vez concluída essa classe, podemos agora, gerar os arquivos HTML em
formato de documentação, para isso, conforme mostra a figura 01, clique no
menu Executar/Gerar javadoc para o seu projeto.

 
  

Figura 01 – Gerando o JavaDoc a partir do NetBeans

Após esse processo, será executado automaticamente o navegador padrão

de sua máquina, exibindo um arquivo na estrutura de HTML conteúdo o
arquivo JavaDoc gerado, veja na figura 02, um trecho de um arquivo desses,
vale ressaltar que, esse arquivo estará armazenado no sub-diretório
\dist\javadoc\ dentro do diretório de seu projeto.

 
  

Figura 02 – Trecho de um arquivo JavaDoc em HTML

6.Conclusões
O Java doc continua sendo um ótimo sistema para documentação interna do
seu software , simples e fácil de utilizar , gera um conjunto padrão de
documentação para suas classes e seus projetos , e portanto imprescindível
para a boa programação em equipe , seu uso porém não substitui a
documentação para o usuário ( manuais operacionais ) afinal documentação
para usuário e documentação para equipes de desenvolvimento tem
finalidades diferente .

Duvidas , criticas e sugestões , envie email para jsantanna@gmail.com