Como usar JavaDoc para documentar as suas classes
Um passo permanece antes que você pode ir a público com a sua biblioteca de classe nova quente ou aplicação: a preparação da documentação para suas classes. Felizmente, Java fornece uma ferramenta chamada JavaDoc
que pode criar automaticamente a 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 meto- em seguida, executar os arquivos de origem através do javadoc comando- voil # 225! 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 terminam 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 ela 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 de exemplos de código de formato (use a tag).
Além disso, você pode incluir especial As tags doc que fornecem informações específicas usado por JavaDoc para formatar as páginas de documentação.
| etiqueta | Explicação |
|---|---|
| @autor | Fornece informações sobre o autor, normalmente o nome de theauthor, endereço de e-mail, informações do site, e em breve. |
| @versão | Indica o número da versão. |
| @desde | Usado para indicar a versão com a qual foi adicionado nesta classe, campo, ormethod. |
| @param | Fornece o nome ea descrição de um orconstructor método. |
| @Retorna | Fornece uma descrição do valor de retorno de um método. |
| @throws | Indica exceções que são lançadas por um orconstructor método. |
| @obsoleto | Indica que a classe, campo ou método está obsoleto andshouldn't ser usado. |
Para lhe dar uma ideia de como os comentários JavaDoc são normalmente utilizados, confira este código.
Note-se que para o Empregado classe para compilar, você também deve fornecer uma classe chamada Endereço, o que representa um endereço. A seguinte 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ódigos 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-privadas. - / ** 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 sobrenome 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 * última nome do empregado * / public setLastName nula (string lastName) {this.lastName = lastName.. -..} / ** Obtém o primeiro nome do empregado * @return Uma string representando primeira * nome * / public string getFirstName do empregado () {return this.firstName -} / ** Define primeiro o nome do empregado * @ Param firstName. Um string que contém o * primeiro nome do empregado * / public void setFirstName (string firstName) {this.firstName = firstName -}... / ** Obtém o salário do empregado * @return Um duplo que representa o salário do empregado * / public getSalary dupla ( ) {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 com lowewriter folha de pagamento *. 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 a residir em primeiro lugar.
Para obter informações mais completas sobre como usar este 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 esta página, basta digitar index.html no prompt de comando depois de executar o comando javadoc. Ou você pode começar seu navegador, navegue até o diretório onde você criou as páginas de documentação, e abra a página index.html.
Se você acha que esta página parece familiar, é porque a documentação da API Java foi criada usando JavaDocs. Então você já deve saber como encontrar o seu caminho em torno destas páginas.
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 gerado esta página a partir do arquivo de origem.
