4 - Documentando as suas classes- uso do java doc

Conforme já vimos na Unidade anterior, podemos comentar trechos do programa em java usando dois tipos de comentário: comentários em linha (//) e multilinha (/**/). Entretanto, o java possui uma forma muito mais poderosa e padronizada de gerar uma documentação reutilizável por outros programadores chamada de javadoc. O javadoc usa comentários multilinhas de forma padronizada para gerar arquivos html que possam servir de documentação online para o código. Mostraremos a seguir um exemplo do código javadoc e o arquivo html que foi gerado:

Exemplo 2_1_007: uso do javadoc.

import com.aiec.teste.*;
/**
* Uma instância dessa classe representa um valor.
*
* @author Andrei
*
*/
public class soma4 {
    /**
  * The valor em formato double
  */
    private double valor;
    /**
  * The valor em formato texto
  */
    private String texto="";
    
    
    public soma4(int valor) /*sobrecarga de construtores. Existem dois 
                            construtores que diferem pelo tipo do  
                                 parâmetro*/
    {
           this.valor=valor;
    }
    public soma4(double valor)
    {
           this.valor=valor;
    }
    public soma4(String valor)
    {
           this.texto=valor;
    }
    private double getValor()
    {
    return this.valor; //busca o atributo valor
    }
    /**
  * Calcula a soma do valor atual do objeto
  * com o parâmetro e retorna o resultado.
  *
  * @param num O valor inteiro a ser somado ao objeto
  *
  * @return a soma do valor com o valor atual do objeto
  */
    public double add(int num)
    {
        this.valor+=valor; 
        return (this.valor);
    }
    /**
  * Calcula= a soma do valor atual do objeto
  * com o parâmetro do tipo double.
  *
  * @param num O valor do tipo double a ser somado ao objeto
  *
  * @return a soma do valor com o valor atual do objeto
  */
    public double add(double valor)
    {
        this.valor+=valor; 
        return (this.valor);
    }
    public static void main(String[] args) {
          soma4 val = new soma4(5.5); //usa o segundo construtor
          val.add(3);
          System.out.print(val.getValor());
    }
}

Podemos verificar que ele incluiu os comentários javadoc que descrevem o conteúdo da classe e o autor. E ainda incluiu os construtores e os métodos existentes. Os comentários javadoc começam sempre por /** e terminam por */. E são usadas tags especiais começando por arroba @ que definem campos específicos a serem preenchidos.