Como usar javadoc para documentar as suas classes
Video: Universidade XTI - JAVA - 101 - Documentação, javadoc e marcas
Conteúdo
Um passo permanece antes que você pode ir a público com a sua biblioteca de classe nova quente ou aplicação: preparando a documentação para suas classes. Felizmente, Java fornece uma ferramenta chamada JavaDoc que pode criar automaticamente documentação baseada em HTML fantasia com base em comentários nos seus arquivos de origem.
Tudo que você tem a fazer é adicionar um comentário para cada classe pública, campo, e metodolo- em seguida, executar os arquivos de origem através do javadoc comando- voilá! você tem a documentação de aparência profissional, baseado na web para suas classes.
Adicionando comentários JavaDoc
A regra básica para a criação de comentários Javadoc é que eles começam com / ** e acabar com * /. Você pode colocar comentários JavaDoc em qualquer um dos três locais diferentes em um arquivo de origem:
Imediatamente antes da declaração de uma classe pública
Imediatamente antes da declaração de um campo público
Imediatamente antes da declaração de um método público ou construtor
Um comentário JavaDoc pode incluir texto que descreve a classe, campo ou método. Cada linha subsequente de um comentário JavaDoc várias linhas geralmente começa com um asterisco. JavaDoc ignora esse asterisco e qualquer espaço em branco entre ele e a primeira palavra na linha.
O texto em um comentário JavaDoc pode incluir marcação HTML se você quiser aplicar a formatação de fantasia. Você deve evitar o uso de tags de cabeçalho (e assim por diante), porque JavaDoc cria aqueles, e seu título tags apenas confundir as coisas. Mas você pode usar tags para negrito e itálico (e ) Ou para formatar exemplos de código (a usar tag).
Além disso, você pode incluir especial As tags doc que fornecem informações específicas usadas por JavaDoc para formatar as páginas de documentação.
| etiqueta | Explicação |
|---|---|
| @autor | Fornece informações sobre o autor, normalmente o autor&rsquo-s nome, endereço de e-mail, informações do site, e assim por em. |
| @versão | Indica o número da versão. |
| @Desde a | Usado para indicar a versão com a qual esta classe, campo ou método foi adicionado. |
| @param | Fornece o nome ea descrição de um método ou construtor. |
| @Retorna | Fornece uma descrição de um método&rsquo-s valor de retorno. |
| @throws | Indica exceções que são lançadas por um método ou construtor. |
| @descontinuada | Indica que a classe, campo ou método é obsoleto e shouldn&rsquo-t ser utilizado. |
Para lhe dar uma ideia de como os comentários JavaDoc são normalmente utilizados, confira este código.
Observe que para o Empregado classe para compilar, você também deve fornecer uma classe chamada Endereço, o que representa um endereço. A seguir classe simples será suficiente:
classe Address pública implementa Cloneable {String public String rua pública da cidade-public String state-public String zipCode-}Este código mostra uma classe de empregado com comentários JavaDoc.
pacote com.lowewriter.payroll - / ** Representa um empregado * @author Doug Lowe * @author LoweWriter.com * @version 1,5 * @since 1,0 * / public class Employee {private String lastName-privada salário dupla cadeia firstName-privada. - / ** Representa o endereço do empregado * / endereço endereço pública -.. / ** Cria um empregado com o nome especificado * @param sobrenome o sobrenome do empregado * @param FirstName o primeiro nome do empregado * / funcionário público (string.. lastName, string firstName) {this.lastName = lastName-this.firstName = firstName-this.address = new Endereço () -} / ** Obtém o último nome do empregado * @return Uma string representando última * o nome do funcionário. *. / string getLastName pública () {return this.lastName -} / ** Define o sobrenome do empregado * @param sobrenome Um string que contém * sobrenome do empregado * / public setLastName vazio (string lastName) {this.lastName = lastName.. -} / ** Obtém o primeiro nome do empregado * @return Uma string representando primeira * nome * / getFi public string do empregado.. rstName () {return this.firstName -}.. / ** Define o primeiro nome do empregado * @param firstName uma string contendo o * primeiro nome do empregado * / setFirstName public void (String firstName) {this.firstName = firstName -} / ** Obtém o salário do empregado * @return a dupla que representa o salário do empregado * / public double getSalary () {return this.salary -}.. / ** Define o salário do empregado * @param lastName Um duplo contendo * salário do empregado. . * / public setSalary void (duplo salário) {this.salary = salary-}}Usando o comando javadoc
o javadoc comando tem algumas dezenas de opções que pode definir, tornando-se um comando complicado de usar. No entanto, você pode ignorar todas essas opções para criar um conjunto básico de páginas de documentação. Basta especificar o caminho completo para todos os arquivos Java você deseja criar documentação para, como este:
javadoc comlowewriterpayroll * .java
o javadoc comando cria as páginas de documentação no diretório atual, então você pode querer mudar para o diretório onde você deseja que as páginas residem em primeiro lugar.
Video: Javadoc: Generando la documentación en Java
Para informações mais completas sobre como usar esse comando, consulte o documentação javadoc no site da Sun.
Visualização de páginas JavaDoc
Depois de executar o comando javadoc, você pode acessar as páginas de documentação, iniciando com a página index.html. Para exibir rapidamente desta página, basta digitar index.html no prompt de comando depois de executar o comando javadoc. Ou você pode iniciar seu navegador, navegue até o diretório onde você criou as páginas de documentação, e abrir a página index.html.
Se você acha desta página parece familiar, é porque a documentação da API Java foi criado usando JavaDocs. Então você já deve saber como encontrar o seu caminho em torno destas páginas.
Video: Javadoc in Eclipse Tutorial
Para olhar a documentação para uma classe, clique no link do nome da classe. Uma página com a documentação completa para a classe vem à tona. JavaDocs gerou esta página a partir do arquivo de origem.
