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