Documentando nossos - Revista easy Java Magazine 18

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.

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.

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.

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 ...