Como criar JavaDoc

JAVADOC

É um utilitário fornecido pela Sun Microsystems junto ao JDK para gerar documentação de códigos Java em formato HTML a partir de comentários no código fonte Java. O JavaDoc é suportado pela maioria dos IDEs de mercado.

O JavaDoc é gerado a partir de um comentário no código fonte iniciado com “/**” e ter finalizado com “*/”. Dentro do comentário JavaDoc é possível usar tags HTML e tags reservadas do JavaDoc precedidas pelo caracter “@”, veja relação das tags reservadas mais utilizada na tabela 1.

Por convenção, sugere-se alocar os blocos de comentários, antes da definição de uma classe, interface, atributos, ou métodos, para introdução conceitual ao referido do código.

TAGS RESERVADAS MAIS COMUNS DO JAVADOC

 

Tag Significado
@author Identifica o autor da classe ou do método.
@deprecated Identifica classes ou métodos obsoletos, e que não se recomenda seu uso porque possivelmente desaparecerá em versões posteriores. É 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 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. Não se deve pode usar em construtores ou métodos “void”
@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 pelo método.
@version Informa a versão do método ou classe.

Tabela 1 – JavaDoc, tags reservadas mais comuns.

EXEMPLO DE COMENTÁRIO JAVADOC

/**Classe para objetos do tipo Funcionários, onde serão contidos, valores e métodos para o mesmo.
* @author Fulano
* @version 1.05
* @since Release 02 da aplicação
*/
public class Funcionarios {…}

/** Método para retorno do salário do funcionário
*   @return Double  - Valor do Salário */
public Double getSalario(){…}

/**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 Ciclano
* @param  diasViagem int - Valor total das vendas do mês.
* @param  valorDeslocamento Double - Valor pago em cada diária.
* @return Double - Valor da diária
*/
 public Double calculaAjudaCusto(int diasViagem, Double valorDeslocamento) throws ArithmeticException {...}

/**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 Beltrano
* @param  valorVendas - Valor total das vendas do mês
* @return Double - Valor do resultado do cálculo conforme a faixa de comissões.
* @throws IllegalArgumentException Se valorVendas é null.
*/
public Double calculaBonificacao(Double valorVendas) throws IllegalArgumentException{...}

/**
* Tenta adicionar um cliente e retorna se esse cliente foi adicionado com sucesso
* @param cliente o cliente a ser adicionado</em>
* @return se o cliente foi corretamente adicionado
*/
public boolean adicionar(Cliente cliente){...}

REFERÊNCIAS

Manoel P. Medeiros, JavaDoc – Implementando documentação através do NetBeans,DevMedia. http://www.devmedia.com.br/articles/viewcomp.asp?comp=2495 acessado em 25/10/2010.
Wikipedia. http://pt.wikilingue.com/es/Javadoc acessado em 26/10/2010.

ORACLE SUN. http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html acessado em 26/10/2010.

Anúncios

2 Comentários

Arquivado em Java

2 Respostas para “Como criar JavaDoc

  1. Francisco Siqueira

    Ainda estou engatinhando no assunto, mas gostei, faço faculdade de Sistemas, mas um dia chego lá.

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s