Este é um post disponível para assinantes MVPEste post também está disponível para assinantes da Easy Java Magazine, Java Magazine
ou para quem possui Créditos DevMedia. Clique aqui para saber mais!
ou para quem possui Créditos DevMedia. Clique aqui para saber mais!
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.
[fechar]
Você não gostou da qualidade deste conteúdo?
(opcional) Você gostaria de comentar o que não lhe agradou?
Easy Java Magazine 18
[Artigo disponível no Leitor Digital DevMedia. Clique aqui para acessá-lo]
> Clique aqui para ler todos os artigos da Easy Java Magazine 18
[Artigo disponível no Leitor Digital DevMedia. Clique aqui para acessá-lo]
> Clique aqui para ler todos os artigos da 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.
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.
"
Este é um post disponível para assinantes MVP
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.
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.
"
A exibição deste artigo foi interrompida.
Este é um post disponível para assinantes MVPEste post também está disponível para assinantes da Easy Java Magazine, Java Magazine
ou para quem possui Créditos DevMedia. Clique aqui para saber mais!
ou para quem possui Créditos DevMedia. Clique aqui para saber mais!
Rodrigo D’agostini Peleias
Bacharel em Ciência da Computação pela PUC-SP e possui as certificações SCJA, SCJP 6, SCWCD 5 e OCBCD 5. Foi Embaixador de Campus na Sun Microsystems em 2009 e atualmente é Analista Programador Java na GoPoints, especializada em desenvolvimento de sistemas voltados a Campanha de Incentivos e CRM de ...
O que você achou deste post?
Cursos relacionados
Publicidade
