JavaDoc � Implementando documenta��o atrav�s do NetBeans

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.

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, como comentei anteriormente, 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

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 pelo JavaDoc.

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 3. exemplo de coment�rio simples

Outro exemplo interresante � a possibilidade de inserç�o de tags HTML, dentro do pr�prio comemt�rio JavaDoc, vamos ver esse exemplo na Listagem 04 que faz o uso das Tag's <b> e <i> para negritar e colocar em it�lico, trechos de nosso coment�rio.


  /** Com essa combinaç�o podemos inserir <b>marcaç�es</b> HTML em <i>nossos</i> coment�rios. */

Listagem 04

Coment�rios em classes

Veja agora na listagem 05, um exemplo de classe cm 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

Automatizando atrav�s do NetBeans

O NetBeans que atualmente encontra-se na vers�o 5.5, 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 o site da NetBeans e adquira maiores informaç�es de como instalar e usar a IDE.

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 Build/Generate javadoc for �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

Conclus�es

Espero que esse artigo tenha elucidado suas principais d�vidas sobre o JavaDoc, e que tamb�m tenha despertado sua atenç�o para o investimento de um pequeno tempo em projeto para gerar a documentaç�o de seu c�digo fonte atrav�s de coment�rios com JavaDoc. Obrigado.