Java 文档注释（学习 Java 编程语言 038）

JDK 包含一个颇有用的工具，叫作 javadoc, 它能够由源文件生成一个 HTML 文档。Java 的 API 文档就是经过标准 Java 类库的源代码运行 javadoc 生成的。

若是在源代码中添加以专用的定界符 /** 开始的注释，能够很容易地生成一个看上去具备专业水准的文档。这是一种很好的方式，由于这种方式能够将代码与文档注释放在一个地方。若是将文档注释放在一个独立的文件中，就有可能会随着时间的推移出现代码和文档注释不一致的问题。然而，因为文档注释与源代码在同一个文件中，在修改源代码的同时，从新运行 javadoc 就能够垂手可得地保持二者的一致性。

1. 注释的插入

javadoc 实用工具从下面几项中抽取信息：
 • 模块
 • 包
 • 公共类和接口
 • 公共的和受保护的字段
 • 公共的和受保护的构造器和方法
能够（并且应该）为以上各个特性编写注释。注释放置在所描述特性的前面。注释一个 /** 开始，并以 */ 结束。

每一个 /** ... */ 文档注释包含标记以及以后紧跟着自由格式文本（free-form text）。标记以 @ 开始，如 @since 或 @param。

自由格式文本的第一句应该是一个概要性的句子。javadoc 工具自动地将这些句子抽取出生成概要页。

在自由格式文本中，可使用 HTML 修饰符，例如：

• 用于强调 <em>...</em>。
• 用于着重强调<strong>...</strong>。
• 用户项目符号列表的 <ul>/<li>。
• 用于包含图像的 <img ...>。
• 用于等宽代码 {@code ...}， 而不是 <code>...</code> —— 这样一来，就不用操心对代码中的 < 字符转移了。

注释：若是文档中有到其余文件的连接，如图像文件（例如，图标或用户界面组件的图像），就应该将这些文件放到包含源文件的目录下的一个子目录 doc-files 中。javadoc 工具将从源目录将 doc-files 目录及其内容拷贝到文档目录中。在连接中须要使用 doc-files 目录，例如：<img src="doc-files/uml_png" alt="UML diagram" >。

2. 类注释

类注释必须放在 import 语句以后，类定义以前。

下面是一个类注释的例子：

/**
 * A {@code Card} object represents a playing card, such
 * as "Queen of Hearts". A card has a suit (Diamond, Heart,
 * Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,
 * 12 = Queen, 13 = King)
 */
public class Card{
    ...
}

没有必要在每一行的开始用星号 *， 例如， 如下注释一样是合法的：

/**
 A {@code Card} object represents a playing card, such
 as "Queen of Hearts". A card has a suit (Diamond, Heart,
 Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,
 12 = Queen, 13 = King)
 */
public class Card{
    ...
}

3. 方法注释

每个方法注释必须放在所描述的方法以前。除了通用标记以外，还可使用下面的标记：

• @param variable description（变量描述）

  这个标记将对当前方法的 “parameters” （参数）部分添加一个条目。这个描述能够占据多行，并可使用 HTML 标记。一个方法的全部 @param 标记必须放在一块儿。

• @return description（描述）

  这个标记将对当前方法添加 “returns” （返回）部分。这个描述能够跨越多行，并可使用 HTML 标记。

• @throws class description（类描述）

  这个标记将添加一个注释，用于表示这个方法有可能抛出异常。

下面是一个合法注释示例：

/**
     * Raises the salary of an employee.
     * @param byPercent the percentage by which to raise the salary (e.g. 10 means 10%)
     * @return the amount of the raise
     */
    public double raiseSalary(double byPercent) {
        double raise = salary * byPercent / 100;
        salary += raise;
        return raise;
    }

4. 字段注释

只须要对公有字段（一般指的是静态常量）创建文档。

/**
     * The "Hearts" card suit
     */
    public static final int HEARST = 1;

5. 通用注释

5.1 用在类文档注释的标记

• @author 姓名

  这个标记将产生一个 “author” (做者）条目。可使用多个 @author 标记，每一个 @author 标记对应一个做者。并非非得使用这个标记，你的版本控制系统可以更好地跟踪做者。

• @version 文本

  这个标记将产生一个 “version”（版本）条目。这里的文本能够是对当前版本的任何描述。

5.2 能够用在全部文件注释的标记

• @since 文本

  这个标记将产生一个 “since” （始于）条目。这里的 text 能够是对引入这个特性的版本的任何描述。例如， @since 1.7.1

• @deprecated 文本

  这个标记将对类、方法或变量添加一个再也不使用的注释。文本中给出了取代的建议。例如，
  @deprecated Use <code>setVIsible(true)</code> instead
  经过 @see 和 @link 标记， 可使用超级连接， 连接到 javadoc 文档的相关部分或外部文档。

• @see 引用

  这个标记将在 “see also” 部分增长一个超级连接。它能够用于类中，也能够用于方法中。这里的 reference（引用）能够有如下选择：
   1. package.class#feature label
   2. <a href="...">label/a>
   2. "text"
  第一种状况是最有用。只要提供类、方法或变量的名字，javadoc 就在文档中插入一个超连接。例如，
   @see com.xiang117.corejava.Employee#raiseSalary(double)
  会创建一个连接到 com.horstmann.corejava.Employee 类的 raiseSalary(double) 方法的超连接。能够省略包名，甚至把包名和类名都省去，这样一来，这会定位于当前包或当前类中。
  须要注意，必定要使用井号（#），而不要使用点号（.）分隔类名与方法名，或类名与变量名。Java 编译器自身能够熟练地肯定点号在分隔包、子包、类、内部类与方法和变量时的不一样含义。可是 javadoc 工具就没有这么聪明了，所以必须对它提供帮助。

  若是 @see 标记后面有一个 < 字符，就须要指定一个超连接。能够超连接到任何 URL。例如：
   @see <a href="www.xiang117.com/corejava.html">The Core Java home page</a>
 @see <a href="http://www.baidu.com">百度</a>
  在上述各类状况下，均可以指定一个可选的标签（label）做为连接锚（link anchor）。若是省略了标签，用户看到的锚就是目标代码名或 URL。

  若是 @see 标记后面有一个双引号（"）字符，文本就会显示在 “see also” 部分。例如，
   @see "Core Java 2 volume 2"

  能够为一个特性添加多个 @see 标记，但必须将它们放在一块儿。

• @link

  若是愿意，还能够在文档注释中的任何位置放置指向其余类或方法的超连接，能够在注释中的任何位置插入一个形式以下的特殊标记：
   {@link package.class#feature label}
  这里的特性描述规则与 @see 标记规相同。

• @index

  在 Java 9 中，还可使用 {@index entry} 标记为搜索框增长一个条目。

6. 包注释

能够直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** . . . */ 文档注释界定就能够了。可是，要想产生包注释，就须要在每个包目录中添加一个单独的文件。能够有以下两个选择：

1. 提供一个名为 package-info.java 的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的 Javadoc 注释，后面是一个 package 语句。它不该该包含更多的代码或注释。
2. 提供一个名为 package.html 的 HTML 文件。会抽取标记 <body>...</body>之间的全部文本。

7. 注释抽取

假设但愿 HTML 文件将放在名为 docDirectory 的目录下。执行如下步骤：

1. 切换到包含想要生成文档的源文件的目录。若是有嵌套的包要生成文档，例如 com.
   xiang117.corejava, 就必须切换到包含子目录 com 的目录（若是提供了 overview.html 文件的
   话，这就是这个文件所在的目录)。
2. 若是是一个包，应该运行命令:
    javadoc -d docDirectory nameOfPackage
   若是要为多个包生成文档，运行:
    javadoc -d docDirectory nameOfPackage1 nameOfPackage2
   若是文件在无名的包中，就应该运行：
    javadoc -d docDirectory *.java

若是省略了 -d docDirectory 选项，那 HTML 文件就会被提取到当前目录下。这样有可能会带来混乱，所以不提倡这种作法。

可使用不少命令行选项对 javadoc 程序进行优化。例如，可使用 -author 和 -version 选项在文档中包含 @author 和 @version 标记（默认状况下，这些标记会被省略 )。另外一个颇有用的选项是 -link，用来为标准类添加超连接。例如，若是使用命令
 javadoc -link http://docs.oracle.com/javase/9/docs/api *.java
那么，全部的标准类库类都会自动地连接到 Oracle 网站的文档。

若是使用 -linksource 选项，则每一个源文件将会被转换为 HTML (不对代码着色，但包含行号)，而且每一个类和方法名将变为指向源代码的超连接。

还能够为全部的源文件提供一个概要注释。把它放在一个相似 overview.html 的文件中，运行 javadoc 工具，并提供命令行选项 -overview filename。将抽取标记 <body>...</body> 之间的全部文本。当用户长导航栏中选择 “Overview”（概览）时，就会显示出这些内容。

有关其余的选项，请查阅 javadoc 工具的联机文档 https://docs.oracle.com/javase/9/javadoc/javadoc.htm。