Documentação Usando o Javadoc Prof. MSc. João Carlos Pinheiro jcpinheiro@cefet-ma.br Versão 2.1 Última Atualização: 04/2005 1
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
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
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
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
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
Tags do javadoc Tags são comandos que permitem formatação adicional da documentação e são sempre iniciados por @ Existem 8 tags permitidas em Java @see @author @version @param @return @exception @deprecated @since 7
Tags do javadoc As tags podem ser aplicados em: classes, atributos e métodos @see - referencia outras classes, métodos ou atributo, incluindo-as (via hiperlinks) na lista See Also @deprecated - aviso desaconselhando o uso de determinadas classes, métodos ou variáveis, que por exemplo podem cair em desuso em novas versões @since - permite especificar quando uma classe, método, ou atributo foi adicionada a API. A sintaxe é: @since versão 8
Tags exclusivas de Classes @author - permite a inclusão de informações sobre o autor, ou autores, tais como nome, email, telefone e etc. Esta tag será ignorada a menos que a opção author seja usada durante a execução de javadoc @version 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
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 de métodos @param @return @exception 10
Tags de Métodos @param - permite a descrição dos parâmetros de um método A sintaxe é: @param nomedoparametro Descrição @return - permite a descrição do significado do valor retornado A sintaxe é: @return descrição @exception - permite a descrição e identificação da exceção (ou exceções) quando da chamada do método. A sintaxe é: @exception nomecompletodaclasse descrição 11
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
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 * @author João Carlos * @version 1.0 */ public abstract class AbstractCadastroPessoa { 14
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. * @param con conexão que será usada para manipular a tabela * pessoa. * @throws SQLException */ protected void iniciarconexoes(connection con) throws SQLException { conconexao = con; enderecocad = new CadastroEnderecoImpl(con); this.carregarpstmtpessoa(); }
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 tag @author (default não gera) -noindex - suprime a geração do índice geral 16
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
Javadoc 18