4.5. Documentação

Quando um programador pondera invocar um método no seu código, deve ser capaz de perceber para que serve esse método e qual a forma de o usar (bem), sem ter que olhar para as instruções que o compõem.

Para este efeito, devemos adicionar a cada método alguma informação que ajude a clarificar

• o que faz, ou seja, qual o seu resultado e/ou os efeitos da sua execução;
• como se usa, ou seja, de que valores precisa (parâmetros) e que requisitos exige.

A assinatura do método – a parte que define o tipo do resultado, o nome do método, e o número, tipo e ordem dos seus parâmetros – já nos dá bastante informação.

Se um parâmetro é do tipo int, sabemos que temos que fornecer um inteiro quando invocamos o método; se o tipo de retorno é String, sabemos o que podemos fazer com o resultado, pois sabemos o seu tipo.

Além disso, se o nome do método e os nomes dos parâmetros forem sugestivos, a tarefa do programador que o vai usar fica facilitada.

Mas, na maior parte das vezes, só a assinatura não é suficiente: às vezes há muito mais a dizer acerca do resultado, dos parâmetros, etc.

Para este efeito, usamos comentários especiais e etiquetas (tags) Javadoc.

O Javadoc é uma aplicação que recebe um ficheiro de texto com extensão java (p. ex., MyClass.java) e gera um ficheiro html (p. ex., MyClass.html) contendo a documentação da classe, ao estilo da documentação das bibliotecas do Java.

O Javadoc interpreta alguns dos comentários que os programadores põem nas suas classes e métodos e usa-os para criar documentação que vai ser útil para todos os programadores que vão usar essas classes e métodos.

Os comentários que o Javadoc usa para a criação da documentação são aqueles que estão entre /** e */. Exemplo:

  /**
    * Nota final arredondada ahs unidades, dadas as notas de exame e projeto
    * @param exame Nota do exame
    * @param proj1 Nota da primeira fase do projeto
    * @param proj2 Nota da segunda fase do projeto
    * @param proj2 Nota da terceira fase do projeto
    * @requires exame, proj1, proj2 e proj3 sao valores no intervalo [0,20]
    * @return A nota final, arredondada ahs unidades; o exame tem peso de 75% e   
              a media de proj1, proj2 e proj3 tem peso de 25%
    */
    static int notaFinal(double exame, double proj1, double proj2, double proj3) {
         double notaCalculada = 0.75 * exame + 0.25 * ((proj1 + proj2 + proj3) / 3) ;
         return (int)(notaCalculada + 0.5);        
    }

O texto que segue a tag @param é entendido como a descrição de um parâmetro.

O texto que segue a tag @requires é entendido como as restrições que existem à invocação do método.

O texto que segue a tag @return é entendido como a descrição do resultado da função.

O compilador de Java ignora os comentários, mas eles são muito úteis para todos os programadores:

• para o programador que criou o método, porque aumenta a legibilidade do código;
• para os programadores que vão invocar o método, porque têm acesso a essa informação (em formato html criada pela aplicação Javadoc).

Para gerar a documentação em formato html de uma classe MyClass contida no ficheiro MyClass.java, pode escrever na linha de comando:

javadoc -package -tag requires:m:''Requires:'' MyClass.java

Abaixo um screenshot da parte correspondente ao método notaFinal na página html gerada com este comando para a nossa classe NotasFinaisLegivel:

Anterior: 4.4. Memória e âmbito das variáveis

Seguinte: 4.6. Repositórios de métodos úteis