简单创建Java API文档

Java SDK 附带的一个实用程序是javadoc工具。此工具用于以HTML文件格式创建Java代码的标准文档。事实上,Java正式使用这个工具来创建自己的库API文档。为了使Java代码文档准备就绪,编写代码时必须遵守某些规范,以便javadoc工具能够运行java文件并创建API文档。在本文中,我们将讨论通常维护的一些关键规范,以在源代码中创建标准Java文档以及javadoc工具的使用。

在Java源代码中使用注释

我们希望在文档中显示一些注释。在源代码中写入这些注释的风格以/ **开始,以* /结尾。在这两个标记中写入的任何文本都被指定为文档注释。这与Java中使用的传统多行注释类似。这两个标记中的文本也可以跨越多行。

/ **这是一个单行文档注释* /

/ **
   这是一个多行文档注释
   这是第二行
   ...第三行
   等等。
* /

通常Java注释(如/ * * /和//)被javadoc工具忽略。与Java中的传统注释不同,文档注释不会转换为字节码。文档注释意图由javadoc工具用于创建HTML文件。因此,我们可以在文档注释中注入HTML标签,如下所示:

/ **这是简单的文字。<B>这是粗体文字</ B> * /

在生成的HTML文件中,在浏览器中打开时,HTML标签中包含的文本将相应地呈现(在本例中为粗体文本)。
有一些特定于javadoc的标签,例如以@开头的工具。这些不是HTML标签。它们被插入到文档注释中,以便javadoc文档可以解析源代码。有很多这样的标签。一些常用的标签如下所述:

  • @author name-text:此标签用于将作者的名称插入生成的文档中,由 name-text指定。可能有多个作者。我们可以为每个 @author标签指定一个名称。有趣的是,当生成文档时,多个名称之间用逗号(,)和名称之间的空格分隔。例如,@author Ravi
    @author Prakash
  • {@code text}:这相当于编写<code> {@ literal} </ code>。这意味着标签中包含的文本将以代码字体呈现。
  • @deprecated deprecated-text:此标记用于将文本指定为已弃用,这意味着将以粗体警告“已弃用”的形式呈现文本。但是,使用 @Deprecated注释,程序元素已被弃用。
  • @参考:此标签将带有文本条目的“另请参见”标题添加到引用的链接。例如,
    • @参阅<a href=” http://docs.oracle.com/javase/8/ “> Java文档这将被渲染为,也可以看看:Java文档
    • @param参数名称描述:此标记用于记录方法和构造函数或类的注释。
    • @Exception class-name description和 @throws class-name描述:这两个标签具有相似的功能,并添加一个Throws副标题到带有类名描述文本的文档。
  • 除了这些少数,还有许多其他标签,以及其具体用途。标签及其描述的完整列表可以在javaDoc标签中找到。在这里,我们将重点介绍如何在源代码中使用这些标签。一旦想法清楚,就不难选择其他需要特定的标签。他们的用法非常相似。

    Javadoc标签示例

    以下示例演示了如何使用源代码编写标签和注释,以及如何在最终文档中反映标签和注释。仅关注用于javadoc工具的标签和注释。

// File: Phone.java
// Phone class with get and set methods
package org.mano.javadoc.example;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * This is a model class to hold phone information
 *
 * @see java.lang.Object
 * @author mano
 */
public class Phone {

   private String area;         // 3-digit
   private String exchange;     // 3-digit
   private String extension;    // 4-digit

   /**
    * No-argument constructor initializes instance variables
    * to null
    * @see #setArea(String)
    * @see #setExchange(String)
    * @see #setExtension(String)
    * @throws Exception in case of invalid value
    */

   public Phone() throws Exception{
      super();
      setArea("000");
      setExchange("000");
      setExtension("0000");
   }

   /**
    * Phone constructor
    * @param area is a 3-digit value
    * @param exchange is a 3-digit value
    * @param extension is a 4-digit value
    * @see #setArea(String)
    * @see #setExchange(String)
    * @see #setExtension(String)
    * @throws Exception in case of invalid value
    */<

   public Phone(String area, String exchange,
         String extension) throws Exception{
      super();
      setArea(area);
      setExchange(exchange);
      setExtension(extension);
   }

   /**
    * Gets the area code
    * @return a <code> string </code>
    * specifying the area code
    */

   public String getArea() {
      return area;
   }
   /**
    * Sets the area code
    * @param area the area code
    * @throws Exception in case of invalid area code
    */

   public void setArea(String area) throws Exception {
      Pattern p=Pattern.compile("^[0-9]{3}$");
      Matcher m=p.matcher(area);
      if(!m.find())
         throw(new Exception("Invalid value!!
            Expects a 3-digit number"));
      this.area = area;
   }
   /**
    * Gets the exchange code
    * @return a <code> string </code> specifying
    * the exchange code
    */

   public String getExchange() {
      return exchange;
   }
   /**
    * Sets the exchange code
    * @param Exchange the exchange code
    * @throws Exception in case of an invalid exchange code
    */

   public void setExchange(String exchange) throws
         Exception {
      Pattern p=Pattern.compile("^[0-9]{3}$");
      Matcher m=p.matcher(exchange)
         throw(new Exception("Invalid value!!
            Expects a 3-digit number"));
      this.exchange = exchange;
   }
   /**
    * Gets the extension code
    * @return a <code> string </code> specifying
    * the extension code
    */

   public String getExtension() {
      return extension;
   }
   /**
    * Sets the extension code
    * @param Extension the extension code
    * @throws Exception in case of invalid extension code
    */

   public void setExtension(String extension) throws
         Exception {
      Pattern p=Pattern.compile("^[0-9]{4}$");
      Matcher m=p.matcher(extension);
      if(!m.find())
         throw(new Exception("Invalid value!!
            Expects a 4-digit number"));
      this.extension = extension;
   }
   /**
    * Convert to standard string format
    * @return a <code> string </code> representing
    * phone number in standard format
    */

   public String toStringFormat(){
      return String.format("(%s) %s-%s",
         getArea(), getExchange(),
          getExtension());
   }
}

生成Java文档

生成源代码文档的最简单方法是通过IDE。Eclipse提供了一个从“ 项目”菜单生成文档的选项。事实上,IDE负责调用javadoc工具,并提供一个GUI界面,以便在生成文档时进行交互。或者,我们可以使用终端中的javadoc命令,并生成源代码文档。因为Eclipse IDE提供了最简单的方法,下面是执行步骤。顺便说一下,源代码必须按照javadoc工具的规范进行装饰。

    • 从Eclipse 的“ 项目”菜单中选择“ 生成Javadoc … ” 。如果没有显示javadoc命令,请在Java SDK安装目录的bin文件夹中导航并找到该工具。
    • 选择将生成Javadoc的一个或多个包。将其他选项(如…成员可见性)保留为默认(Public)并使用标准doclet。
    • 图1:选择一个包
    • 提供文件标题; 确保检查所有基本选项和文档标签。不要忘记检查应该生成链接的所有引用的归档和项目。否则,生成的HTML文档将不包含引用的类和接口的任何链接。
    • 图2:提供标题
    • 最后,生成的文档可以设置为与特定的Java版本兼容。可选地,设置也可以保存为Ant脚本以供将来参考。完成。
    • 图3:指定Java版本
    • 这些步骤将生成源代码的文档,类似于指定文件夹中的标准Java API文档。图4显示了从源代码创建的文档的输出。
    • 图4:文档输出

    结论

    当javadoc执行时,它显示从Java源文件创建的HTML文件的名称。创建的HTML文件的数量取决于源文件中关联的类或接口的数量。HTML文件存储在由javadoc工具创建的doc目录中。该目录中创建的起始HTML文件是index.html文件。一旦在浏览器中打开,其左框架包含另一个HTML页面,称为allclasses-frame.html,链接到源代码中的类。正确的框架包含页面本身。