Documentação da API:
- Toda API deve ser documentada para facilitar seu uso.
- Tradicionalmente, a documentação era gerada manualmente, mas com o Javadoc isso se tornou automatizado.
Comentários doc:
- Os comentários doc são especialmente formatados para serem lidos pelo Javadoc.
- Eles devem ser usados em classes, interfaces, construtores, métodos e campos expostos da API.
- É importante mantê-los sincronizados com o código.
Convenções:
- As convenções de comentários doc não fazem parte da linguagem, mas todo desenvolvedor Java deve conhecê-las.
- Tags úteis: {@code}, {@literal}, {@implSpec}, {@index}.
Documentação de métodos:
- Deve descrever o contrato entre o método e o cliente.
- Deve listar:
- Precondições (usualmente descritas com @throws para exceções).
- Pós-condições (o que será verdade após a execução bem-sucedida).
- Efeitos colaterais (mudanças não óbvias no estado do sistema).
- Utilizar @param para cada parâmetro, @return para o retorno e @throws para exceções.
Escrita de comentários:
- O texto após @param ou @return deve ser uma frase nominal.
- O texto após @throws deve começar com "se" e descrever a condição que gera a exceção.
- Convencionado que as frases não têm ponto final.
Elementos HTML:
- Tags como
e podem ser usadas dentro dos comentários doc.
- A tag {@code} é usada para formatar código, e {@literal} para incluir caracteres especiais como < e >.
Herança de documentação:
- Comentários podem ser herdados com {@inheritDoc}, reduzindo a duplicação de documentação.
Documentação adicional:
Em casos complexos, recomenda-se documentos externos complementares.
Exemplo de código com Javadoc:
/**
* Representa uma conta bancária com operações de saque e depósito.
* <p>
* Essa classe é thread-safe e serializável.
*
* @implSpec A implementação utiliza uma trava interna para garantir a consistência do saldo.
*/
public class ContaBancaria {
private double saldo;
/**
* Deposita um valor na conta.
*
* @param valor o valor a ser depositado, deve ser positivo
* @throws IllegalArgumentException se o valor for negativo
*/
public synchronized void depositar(double valor) {
if (valor <= 0) {
throw new IllegalArgumentException("O valor deve ser positivo.");
}
saldo += valor;
}
/**
* Retira um valor da conta.
*
* @param valor o valor a ser retirado, deve ser positivo e menor que o saldo atual
* @throws IllegalArgumentException se o valor for negativo ou maior que o saldo
*/
public synchronized void sacar(double valor) {
if (valor <= 0 || valor > saldo) {
throw new IllegalArgumentException("Valor inválido.");
}
saldo -= valor;
}
/**
* Retorna o saldo atual da conta.
*
* @return o saldo atual
*/
public synchronized double getSaldo() {
return saldo;
}
}
Esse exemplo demonstra o uso correto de comentários doc para uma classe ContaBancaria, incluindo tags como @param, @return, @throws e @implSpec
Top comments (0)