Documentando nossos - Revista easy Java Magazine 18

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.

Fique por dentro
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 "

[...] continue lendo...

Artigos relacionados