Documentação Usando o Javadoc

Transcrição

1 Documentação Usando o Javadoc Prof. MSc. João Carlos Pinheiro [email protected] Versão 2.1 Última Atualização: 04/2005 1

2 Comentários e Documentação Comentários em Java Existem três tipos de comentários possíveis: o proveniente da linguagem C que é útil para comentários de grandes blocos de código iniciando com e cuja sintaxe começa com /* e continuando até o próximo */ o proveniente do C++, útil para comentários curtos em meio ao corpo código, cuja sintaxe começa com // estendendo-se até o fim da linha os comentários especiais de documentação, úteis na geração da documentação automática. Sua sintaxe inicia-se com /** continuando até o próximo */ 2

3 Dicas sobre os comentários Os comentários devem ser usados para explicar códigos complexos e revelar informações sobre o código que de outras formas seriam difíceis de descobrir Exemplo de um comentário inadequado x = 5; // configura a variável x igual a 5 Exemplo de um comentário adequado // Aplica 5% de desconto para todos os pedidos // acima de R$1000,00 de acordo com a campanha // Fome Zero do Governo Federal if (totalpedido >= VALOR_DESCONTO) { totalpedido = totalpedido * (1 - PERCENTUAL_DESCONTO); } 3

4 Documentação de Comentários O javadoc extrai os comentários especiais de documentação embutidos no código fonte, gerando um arquivo no formato HTML Processa apenas comentários de documentação para membros de classe declarados como public ou protected Comentários em membros do tipo private ou package ( default ) serão ignorados, se não forem explicitados no comando javadoc 4

5 Comentários e Documentação Há duas maneiras de se trabalhar com o javadoc: Embutindo-se código HTML e, Usando tags de documentação Embutindo HTML O javadoc permite o uso de comandos HTML diretamente nos comentários de documentação É permitido o uso de qualquer comando de formatação, tal como <TT> e <b>, mas não se pode fazer uso de comandos estruturais, tais como <H2> e <hr> Pois o javadoc já insere seus próprios comandos estruturais 5

6 Comentários e Documentação Exemplo: /** É possível <b> até </b> gerar uma lista <ol> <li> item um <li> item dois <li> item três </ol> */ 6

7 Tags do javadoc Tags são comandos que permitem formatação adicional da documentação e são sempre iniciados Existem 8 tags permitidas 7

8 Tags do javadoc As tags podem ser aplicados em: classes, atributos e - referencia outras classes, métodos ou atributo, incluindo-as (via hiperlinks) na lista See - aviso desaconselhando o uso de determinadas classes, métodos ou variáveis, que por exemplo podem cair em desuso em novas - permite especificar quando uma classe, método, ou atributo foi adicionada a API. A sintaxe versão 8

9 Tags exclusivas de - permite a inclusão de informações sobre o autor, ou autores, tais como nome, , telefone e etc. Esta tag será ignorada a menos que a opção author seja usada durante a execução de permite a inclusão do número de versão da classe Exige a opção version quando você está executando o javadoc; do contrário, a tag será ignorada 9

10 Tags de Métodos Esse tipo de documentação permite o uso de tags reservados para parâmetros, valores de retorno e exceções Tags exclusivas @exception 10

11 Tags de - permite a descrição dos parâmetros de um método A sintaxe nomedoparametro - permite a descrição do significado do valor retornado A sintaxe - permite a descrição e identificação da exceção (ou exceções) quando da chamada do método. A sintaxe nomecompletodaclasse descrição 11

12 O utilitário Javadoc Gera uma página para cada classe, com links para membros da classe e páginas de outras classes relacionadas O comando javadoc tem a seguinte sintaxe: javadoc [opções] nomedopacote ou javadoc [opções] nomesdaclasses 12

13

14 Exemplo - Documentação da classe Conta /** * <p>esta classe é uma classe especializada em manipular os dados relacionados * à tebela pessoa no banco de dados. Deve-se passar a conexão que a classe * deve utilizar para trabalhar com a tabela pessoa. <br> * Esta classe deve ser estendida pois, segundo a lógica do sistema, não * será necessário o cadastro de uma entidade pessoa, mas sim de Alunos e * professores, inicialmente. * <p><font color="red"> O método iniciarconexoes() deve ser chamado antes de * qualquer outro método desta classe, pois ee é responsável por carregar os * preparedstatement a partir da conexão que recebe como parâmetro. * </FONT> * Exemplo de uso: * <pre> classe Aluno extends Pessoa {...} </pre> * Melhorias: Fazer com que a conexão seja passada pelo construtor da classe João Carlos 1.0 */ public abstract class AbstractCadastroPessoa { 14

15 private PreparedStatement pstmtinseripessoa = null; private PreparedStatement pstmtatualizapessoa = null; private PreparedStatement pstmtlocalizapessoa = null; private CadastroEnderecoIF enderecocad = null; protected Connection conconexao = null; /** * <p>este método carrega os preparedstatement da * tabela pessoa e endereco.ele deve ser chamado antes de qualquer * utilização. con conexão que será usada para manipular a tabela * pessoa. SQLException */ protected void iniciarconexoes(connection con) throws SQLException { conconexao = con; enderecocad = new CadastroEnderecoImpl(con); this.carregarpstmtpessoa(); }

16 Utilitário Javadoc Principais opções: -classpath - conjunto de diretórios separados por vírgula ou dois pontos (unix) onde estão as classes já compiladas -d - diretório onde o HTML vai ser gerado -author - gerar informação da (default não gera) -noindex - suprime a geração do índice geral 16

17 Javadoc Principais opções (continuação): -notree - suprime a geração da hierarquia de classes -private, protected, package - documenta membros com visibilidade até a indicada -use - cria páginas documentando o uso de packages windowtitle - texto para a barra de título do browser header, footer, bottom - texto HTML em todas as páginas 17

18 Javadoc 18