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 */
/** Exemplo básico de um comentário em JavaDoc
* com mais de uma linha.
*/
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. |
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 */
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. */
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;
}
}
}
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”.
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.
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.
