LTP CAP03 VA10 JAVADOC

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.