1
00:00:05,010 --> 00:00:07,399
Assim como existe toda 
a documentação do Java

2
00:00:07,399 --> 00:00:10,249
dentro do Java API Specification 
na Oracle,

3
00:00:10,249 --> 00:00:13,909
você também pode criar
a especificação do seu projeto

4
00:00:13,909 --> 00:00:15,679
através do uso 
de Javadoc.

5
00:00:15,679 --> 00:00:19,679
Para poder utilizar o Javadoc
para documentar as suas classes,

6
00:00:19,679 --> 00:00:24,570
métodos e atributos, 
você precisa utilizar o "/**".

7
00:00:24,570 --> 00:00:29,606
A partir do /**, você pode fazer 
como se fosse uma outra programação.

8
00:00:29,606 --> 00:00:34,370
Você vai poder utilizar tags
e referenciar as informações dessas tags.

9
00:00:34,370 --> 00:00:37,931
Essas tags serão lidas
por um executável Javadoc,

10
00:00:37,931 --> 00:00:41,710
que irá gerar todo um HTML
com todas essas informações.

11
00:00:41,710 --> 00:00:43,581
Para utilizar 
as tags do Javadoc

12
00:00:43,581 --> 00:00:47,021
você sempre vai utilizar 
arroba e o nome da tag.

13
00:00:47,021 --> 00:00:50,841
As principais tags são:
@author, que é para você indicar

14
00:00:50,841 --> 00:00:54,221
qual é o nome do desenvolvedor
daquele programa.

15
00:00:54,221 --> 00:00:57,891
O @deprecated, que é para você
indicar que aquele método,

16
00:00:57,891 --> 00:00:59,341
ou aquele atributo, 
ou aquela classe,

17
00:00:59,341 --> 00:01:02,276
já não está mais em uso,
e aí você pode indicar

18
00:01:02,276 --> 00:01:06,141
qual a outra classe que está
substituindo aquela classe,

19
00:01:06,141 --> 00:01:07,276
ou, enfim, 
aquele método.

20
00:01:07,276 --> 00:01:10,701
O @param, que é para definir
um parâmetro do método,

21
00:01:10,701 --> 00:01:14,311
ou seja, quais são os parâmetros
e a descrição desses parâmetros

22
00:01:14,311 --> 00:01:15,626
que estão de entrada
para um método.

23
00:01:15,626 --> 00:01:20,551
O @return, que é para documentar
um valor de retorno de um método.

24
00:01:20,551 --> 00:01:24,551
Só note o seguinte: essa tag não
deve ser utilizada para construtores

25
00:01:24,551 --> 00:01:26,886
ou para métodos 
que não têm retorno.

26
00:01:26,886 --> 00:01:31,658
O @see, que é simplesmente para você 
indicar uma outra documentação

27
00:01:31,658 --> 00:01:34,428
relacionada àquele 
método classe

28
00:01:34,428 --> 00:01:37,031
ou atributo no qual 
você está documentando.

29
00:01:37,031 --> 00:01:40,228
O @since, que é para você
identificar desde quando

30
00:01:40,228 --> 00:01:44,228
aquela alteração ou aquela 
construção foi realizada.

31
00:01:44,228 --> 00:01:47,348
O @exception, que,
assim como o @throws,

32
00:01:47,348 --> 00:01:52,288
são utilizados para poder identificar
qual o tipo de erro ou de exceção

33
00:01:52,288 --> 00:01:54,161
que um método
pode lançar.

34
00:01:54,161 --> 00:01:58,378
E o @version, que é para você
identificar qual é o número daquela versão,

35
00:01:58,378 --> 00:02:00,331
seja para um método
ou para uma classe.

36
00:02:00,331 --> 00:02:03,537
Vou realizar agora um teste
fazendo a documentação

37
00:02:03,537 --> 00:02:07,421
dentro da classe conta e depois 
gerando toda essa documentação.

38
00:02:07,421 --> 00:02:10,087
Logo de início, antes 
da declaração da classe,

39
00:02:10,087 --> 00:02:12,597
eu já identifiquei
informações sobre a classe.

40
00:02:12,597 --> 00:02:15,237
Então, eu utilizei 
o /**,

41
00:02:15,237 --> 00:02:18,227
descrevi do que se trata
aquela classe,

42
00:02:18,227 --> 00:02:20,717
coloquei qual é o autor
daquela classe

43
00:02:20,717 --> 00:02:23,047
e qual é a versão
daquela classe.

44
00:02:23,047 --> 00:02:27,654
Logo em seguida, eu criei a documentação
para cada um dos métodos da classe.

45
00:02:27,654 --> 00:02:29,986
Logo acima
do método depositar,

46
00:02:29,986 --> 00:02:32,716
eu coloquei a descrição 
a respeito do método

47
00:02:32,716 --> 00:02:36,716
e qual é a descrição
do parâmetro valor.

48
00:02:36,716 --> 00:02:40,156
Logo em seguida, eu realizei
a documentação do método retirar.

49
00:02:40,156 --> 00:02:42,869
Descrevi 
o que o método fará,

50
00:02:42,869 --> 00:02:45,889
também descrevi 
o parâmetro de entrada

51
00:02:45,889 --> 00:02:48,779
e coloquei mais uma tag,
que é a tag see,

52
00:02:48,779 --> 00:02:50,969
que vai apontar 
para um outro método,

53
00:02:50,969 --> 00:02:52,678
que é o método
depositar,

54
00:02:52,678 --> 00:02:56,509
para que, toda vez que qualquer
programador veja essa documentação,

55
00:02:56,509 --> 00:02:59,999
ele visualize que, tanto o método
retirar quanto o método depositar,

56
00:02:59,999 --> 00:03:01,398
têm alguma relação.

57
00:03:01,398 --> 00:03:04,629
E, por fim, eu também documentei
o método verificarSaldo,

58
00:03:04,629 --> 00:03:07,999
colocando simplesmente
a declaração do que o método faz

59
00:03:07,999 --> 00:03:11,049
e também qual é o tipo
de retorno desse método,

60
00:03:11,049 --> 00:03:14,528
informando que ele vai retornar
o valor do saldo da conta.

61
00:03:14,528 --> 00:03:18,449
Note o seguinte: só de realizar
esses comentários no padrão Javadoc,

62
00:03:18,449 --> 00:03:20,741
ao passar o mouse 
em cima do método,

63
00:03:20,741 --> 00:03:23,761
ele já mostra essa 
descrição que nós fizemos

64
00:03:23,761 --> 00:03:25,548
no padrão 
de documentação.

65
00:03:25,548 --> 00:03:28,851
Mas se eu quiser gerar
todo um HTML a respeito,

66
00:03:28,851 --> 00:03:30,841
então eu tenho 
um comando para fazer isso,

67
00:03:30,841 --> 00:03:32,343
que é o comando
Javadoc.

68
00:03:32,343 --> 00:03:34,761
Eu posso fazer esse 
comando manualmente

69
00:03:34,761 --> 00:03:36,431
através do comando
Javadoc,

70
00:03:36,431 --> 00:03:40,091
que é um executável que fica 
na mesma pasta do JDK

71
00:03:40,091 --> 00:03:43,321
onde estão os comandos
de compilação e interpretação,

72
00:03:43,321 --> 00:03:45,983
mas eu também posso vir
através do Eclipse.

73
00:03:45,983 --> 00:03:49,291
Para poder gerar todo 
o HTML dessa documentação,

74
00:03:49,291 --> 00:03:51,891
basta eu acessar 
a opção Project,

75
00:03:51,891 --> 00:03:54,311
Generate Javadoc.

76
00:03:54,311 --> 00:03:56,301
Nessa opção aqui eu 
preciso identificar

77
00:03:56,301 --> 00:03:59,051
qual é o comando 
de geração desse Javadoc,

78
00:03:59,051 --> 00:04:02,331
porque existem várias outras
ferramentas de geração.

79
00:04:02,331 --> 00:04:05,551
Então, eu vou colocar qual é
o endereço onde está esse comando.

80
00:04:05,551 --> 00:04:07,991
Normalmente 
está na pasta bin.

81
00:04:07,991 --> 00:04:10,031
Basta selecionar
o comando Javadoc

82
00:04:10,031 --> 00:04:14,265
que está dentro 
da pasta bin do seu JDK.

83
00:04:14,265 --> 00:04:16,855
Uma vez selecionado
o comando Javadoc,

84
00:04:16,855 --> 00:04:20,125
eu seleciono quais são
as classes dos projetos

85
00:04:20,125 --> 00:04:22,095
que eu quero gerar 
a documentação.

86
00:04:22,095 --> 00:04:25,355
Nesse caso, só fizemos a documentação
a partir da classe conta.

87
00:04:25,355 --> 00:04:27,455
Então, eu seleciono 
a classe conta

88
00:04:27,455 --> 00:04:29,465
e também coloco
qual a pasta destino

89
00:04:29,465 --> 00:04:31,035
para gerar essa 
documentação.

90
00:04:31,035 --> 00:04:33,365
Clico em finish, 
ele verifica se eu quero

91
00:04:33,365 --> 00:04:37,065
alterar o local de destino 
dessa documentação

92
00:04:37,065 --> 00:04:40,565
ou também substituir
algumas informações que ali estão,

93
00:04:40,565 --> 00:04:43,135
eu posso 
simplesmente confirmar,

94
00:04:43,135 --> 00:04:47,025
e é feita automaticamente 
a geração de todo o HTML

95
00:04:47,025 --> 00:04:48,580
com essa 
documentação.

96
00:04:48,580 --> 00:04:51,555
Ao término da execução, 
você vai poder observar

97
00:04:51,555 --> 00:04:55,555
na sua estrutura do projeto que ele
gerou uma nova pasta chamada doc

98
00:04:55,555 --> 00:04:57,645
com diversos
arquivos HTML.

99
00:04:57,645 --> 00:05:00,595
Basta você acessar 
o arquivo index.html

100
00:05:00,595 --> 00:05:02,485
no navegador 
do próprio Eclipse

101
00:05:02,485 --> 00:05:04,295
ou em qualquer 
outro navegador.

102
00:05:04,295 --> 00:05:07,725
Caso seja pelo Eclipse,
basta ir à opção Open With,

103
00:05:07,725 --> 00:05:12,255
Web Browser, e ele vai abrir
toda a documentação do seu projeto

104
00:05:12,255 --> 00:05:15,045
no padrão
de Java API Specification.

105
00:05:15,045 --> 00:05:18,305
Claro que, nesse caso,
temos somente a classe conta,

106
00:05:18,305 --> 00:05:21,465
e a classe conta com as descrições 
que nós colocamos

107
00:05:21,465 --> 00:05:24,040
lá na documentação
dentro do programa.

108
00:05:24,040 --> 00:05:27,995
O Javadoc, ou qualquer outro
software de geração de documentação,

109
00:05:27,995 --> 00:05:30,005
é muito importante
para a programação.

110
00:05:30,005 --> 00:05:31,880
Eu sei que dá
uma certa preguiça,

111
00:05:31,880 --> 00:05:35,305
mas é importante porque, de fato,
essa documentação pode ser muito útil

112
00:05:35,305 --> 00:05:37,840
para outros desenvolvedores
desse seu projeto.