Artigos Canal Mais Documentando nossos - Revista easy Java Magazine 18
Por que eu devo ler este artigo:Apresentação e aplicação do JavaDoc nos nossos projetos, e porque podemos nos beneficar do seu uso. Neste artigo, mostraremos brevemente como consultar o JavaDoc da API padrão da plataforma Java e enfatizaremos a criação de guias para os nossos projetos. Apresentaremos os elementos necessários para a criação da documentação a partir de um exemplo prático do dia-a-dia. Além disso, demonstraremos algumas boas práticas a serem adotadas ao comentar os nossos códigos-fontes, mostrando por fim o que devemos e como documentar, e como gerar o JavaDoc a partir dos comandos do JDK e pelas IDEs Eclipse e NetBeans.

Fornecer um recurso para a documentação das nossas classes e seus respectivos elementos, como métodos e atributos. Através do JavaDoc podemos criar guias descrevendo as classes envolvidas nos nossos projetos. Este tipo de documentação é muito importante, pois outros desenvolvedores podem utilizar uma biblioteca desenvolvida por nós. Consequentemente, a disponibilização de uma referência para o nosso projeto pode auxiliar o profissional na compreensão do seu funcionamento. Ademais, com o JavaDoc temos à disposição um recurso para auxiliar na compreensão de classes durante a manutenção de código-fonte, que pode ter sido desenvolvido por nós mesmos ou por outros profissionais.

Além de ser um recurso útil para a consulta de informações sobre determinada classe, o JavaDoc oferece diversos tipos de informações além de simples comentários sobre cada elemento. Informações como versão e autor de uma classe e parâmetros recebidos e exceções lançadas por um método e/ou construtor são importantes para a compreensão de uma classe como um todo. Com o JavaDoc, o profissional tem um poderoso recurso à sua disposição para auxiliá-lo tanto na documentação dos seus projetos a ser disponibilizado à comunidade, como para ajudá-lo na compreensão da API Java e de bibliotecas criadas por terceiros.

Ao utilizarmos um recurso da API nativa da plataforma Java e/ou uma classe de um framework codificado por outros profissionais, muitas vezes não sabemos a funcionalidade de determinada classe à primeira vista. Informações como o que faz cada método e o que significa cada um dos seus parâmetros são muito importantes para o entendimento dos recursos disponibilizados. Outras informações como nome do autor, data de criação e versão que se encontra o elemento também podem ser importantes em arquivos de documentação de projetos. Estes tipos de dados são úteis caso o desenvolvedor esteja utilizando o recurso há algum tempo e deseja fazer uma atualização deste ou uma contribuição para o desenvolvimento de um framework já lançado no mercado, por exemplo.

Como exemplo, utilizando a classe HashMap, referente ao framework/API de Collection, muitas vezes um iniciante na linguagem pode vir a ter dificuldades no seu uso pela primeira vez. Caso o profissional não tenha um guia, uma documentação adequada desta classe, poderá gastar um tempo maior para aprender sobre as funcionalidades disponibilizadas por ela. Sem a documentação, um dos meios para o aprendizado é a construção de exemplos como testes para a compreensão dos métodos disponibilizados por HashMap.

O JavaDoc foi criado com o objetivo de oferecer ao desenvolvedor um recurso para possibilitar a criação de guias para os seus projetos de software. Por exemplo, se elaborarmos um framework a ser disponibilizado para a comunidade, como bons desenvolvedores o nosso papel é fornecer um guia de utilização desta ferramenta. O JavaDoc desempenha bem esse papel.

A partir do uso do JavaDoc, o desenvolvedor tem à sua disposição um guia para as classes dos seus projetos. Ao navegarmos nas páginas de documentação da linguagem, encontramos descrições para as classes e seus respectivos métodos, atributos, etc. Informações como data de compilação e descrição parâmetros também são disponibilizadas por meio do JavaDoc, facilitando a compreensão e aprendizado.

Com base neste contexto, o objetivo deste artigo é mostrar ao leitor a importância do JavaDoc, enfatizando a necessidade da documentação das classes desenvolvidas e a adoção desta ferramenta para a criação de guias para os nossos projetos. Introduziremos o artigo mostrando como consultar a documentação da API padrão da linguagem e a sua importância no decorrer dos nossos projetos. Dando continuidade à publicação, enfatizaremos como documentar nosso próprios projetos, e a importância de documentá-los para que outras pessoas possam empregá-los. Durante este tópico, mostraremos também a criação de comentários e a utilização das tags padrões do JavaDoc.

A aplicação de boas práticas na geração de documentação também será abordada. Neste tópico, mostraremos ao leitor como fazer o melhor uso do JavaDoc. Finalizando o estudo, destacaremos como gerar os arquivos de guia para os nossos projetos através dos comandos oferecidos pelo JDK e pelas IDEs NetBeans e Eclipse.

Nota: Apesar de o artigo abordar a geração de documentação a partir dos comandos disponibilizados pelo JDK e pelas IDEs NetBeans e Eclipse, os exemplos apresentados no artigo serão desenvolvidos na última IDE mencionada, o Eclipse Indigo.

Documentação da API padrão da plataforma Java

A documentação da API padrão da plataforma Java é disponibilizada desde as primeiras versões da linguagem. No site da Sun Microsystems (e hoje em dia, no site da Oracle), o desenvolvedor já encontrava as referências para classes e seus respectivos métodos e atributos.

O objetivo desta ferramenta é servir como uma referência para o profissional compreender o funcionamento de determinada classe da plataforma. Informações como para que serve uma classe e como funcionam seus respectivos métodos, atributos e possíveis exceções são encontradas nos arquivos disponibilizados pela equipe de desenvolvimento do Java. Ao consultarmos a informação da classe StringBuffer, por exemplo, encontramos descrições sobre o funcionamento de cada construtor e método da classe. Encontramos também uma breve descrição sobre cada parâmetro que cada método ou construtor recebe e quais exceções podem ser lançadas pelo uso indevido de cada um.

Para o maior entendimento do leitor, mostraremos um breve exemplo de como acessar a documentação da API padrão da plataforma.

Acessando e navegando na documentação da API padrão do Java

Como o foco principal desta publicação é mostrar como documentar os nossos projetos, nesta parte demonstraremos brevemente como fazer o acesso e navegação na documentação da linguagem.

Ao entrarmos com a URL http://docs.oracle.com/javase/7/docs/api/, será exibida a página do guia da API Java, conforme a Figura 1.

Tela da API padrão da plataforma Java
Figura 1. Tela da API padrão da plataforma Java

Na página do JavaDoc, reparamos que a tela está divida em três seções. A Figura 2 mostra a parte referente ao canto superior esquerdo ampliada.

Seção referente aos links para acesso aos pacotes das classes
Figura 2. Seção referente aos links para acesso aos pacotes das classes

Nesta seção encontramos um link com a informação All Classes, e abaixo deste uma lista com links referentes aos pacotes das classes padrões da API. Estes links servem como filtro para as classes a serem exibidas na seção referente ao canto inferior esquerdo. Ao selecionar o link All Classes, uma lista com todos os elementos da API padrão de Java serão exibidos, de acordo com a ...

Quer ler esse conteúdo completo? Tenha acesso completo