Assim como existe toda a documentação do Java
dentro do Java API Specification na Oracle,
você também pode criar a especificação do seu projeto
através do uso de Javadoc.
Para poder utilizar o Javadoc para documentar as suas classes,
métodos e atributos, você precisa utilizar o "/**".
A partir do /**, você pode fazer como se fosse uma outra programação.
Você vai poder utilizar tags e referenciar as informações dessas tags.
Essas tags serão lidas por um executável Javadoc,
que irá gerar todo um HTML com todas essas informações.
Para utilizar as tags do Javadoc
você sempre vai utilizar arroba e o nome da tag.
As principais tags são: @author, que é para você indicar
qual é o nome do desenvolvedor daquele programa.
O @deprecated, que é para você indicar que aquele método,
ou aquele atributo, ou aquela classe,
já não está mais em uso, e aí você pode indicar
qual a outra classe que está substituindo aquela classe,
ou, enfim, aquele método.
O @param, que é para definir um parâmetro do método,
ou seja, quais são os parâmetros e a descrição desses parâmetros
que estão de entrada para um método.
O @return, que é para documentar um valor de retorno de um método.
Só note o seguinte: essa tag não deve ser utilizada para construtores
ou para métodos que não têm retorno.
O @see, que é simplesmente para você indicar uma outra documentação
relacionada àquele método classe
ou atributo no qual você está documentando.
O @since, que é para você identificar desde quando
aquela alteração ou aquela construção foi realizada.
O @exception, que, assim como o @throws,
são utilizados para poder identificar qual o tipo de erro ou de exceção
que um método pode lançar.
E o @version, que é para você identificar qual é o número daquela versão,
seja para um método ou para uma classe.
Vou realizar agora um teste fazendo a documentação
dentro da classe conta e depois gerando toda essa documentação.
Logo de início, antes da declaração da classe,
eu já identifiquei informações sobre a classe.
Então, eu utilizei o /**,
descrevi do que se trata aquela classe,
coloquei qual é o autor daquela classe
e qual é a versão daquela classe.
Logo em seguida, eu criei a documentação para cada um dos métodos da classe.
Logo acima do método depositar,
eu coloquei a descrição a respeito do método
e qual é a descrição do parâmetro valor.
Logo em seguida, eu realizei a documentação do método retirar.
Descrevi o que o método fará,
também descrevi o parâmetro de entrada
e coloquei mais uma tag, que é a tag see,
que vai apontar para um outro método,
que é o método depositar,
para que, toda vez que qualquer programador veja essa documentação,
ele visualize que, tanto o método retirar quanto o método depositar,
têm alguma relação.
E, por fim, eu também documentei o método verificarSaldo,
colocando simplesmente a declaração do que o método faz
e também qual é o tipo de retorno desse método,
informando que ele vai retornar o valor do saldo da conta.
Note o seguinte: só de realizar esses comentários no padrão Javadoc,
ao passar o mouse em cima do método,
ele já mostra essa descrição que nós fizemos
no padrão de documentação.
Mas se eu quiser gerar todo um HTML a respeito,
então eu tenho um comando para fazer isso,
que é o comando Javadoc.
Eu posso fazer esse comando manualmente
através do comando Javadoc,
que é um executável que fica na mesma pasta do JDK
onde estão os comandos de compilação e interpretação,
mas eu também posso vir através do Eclipse.
Para poder gerar todo o HTML dessa documentação,
basta eu acessar a opção Project,
Generate Javadoc.
Nessa opção aqui eu preciso identificar
qual é o comando de geração desse Javadoc,
porque existem várias outras ferramentas de geração.
Então, eu vou colocar qual é o endereço onde está esse comando.
Normalmente está na pasta bin.
Basta selecionar o comando Javadoc
que está dentro da pasta bin do seu JDK.
Uma vez selecionado o comando Javadoc,
eu seleciono quais são as classes dos projetos
que eu quero gerar a documentação.
Nesse caso, só fizemos a documentação a partir da classe conta.
Então, eu seleciono a classe conta
e também coloco qual a pasta destino
para gerar essa documentação.
Clico em finish, ele verifica se eu quero
alterar o local de destino dessa documentação
ou também substituir algumas informações que ali estão,
eu posso simplesmente confirmar,
e é feita automaticamente a geração de todo o HTML
com essa documentação.
Ao término da execução, você vai poder observar
na sua estrutura do projeto que ele gerou uma nova pasta chamada doc
com diversos arquivos HTML.
Basta você acessar o arquivo index.html
no navegador do próprio Eclipse
ou em qualquer outro navegador.
Caso seja pelo Eclipse, basta ir à opção Open With,
Web Browser, e ele vai abrir toda a documentação do seu projeto
no padrão de Java API Specification.
Claro que, nesse caso, temos somente a classe conta,
e a classe conta com as descrições que nós colocamos
lá na documentação dentro do programa.
O Javadoc, ou qualquer outro software de geração de documentação,
é muito importante para a programação.
Eu sei que dá uma certa preguiça,
mas é importante porque, de fato, essa documentação pode ser muito útil
para outros desenvolvedores desse seu projeto.