Java 文档注释(学习 Java 编程语言 038)

JDK 包含一个很有用的工具,叫做 javadoc, 它可以由源文件生成一个 HTML 文档。Java 的 API 文档就是通过标准 Java 类库的源代码运行 javadoc 生成的。

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

1. 注释的插入

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

每个 /** ... */ 文档注释包含标记以及之后紧跟着自由格式文本(free-form text)。标记以 @ 开始,如 @since@param

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

在自由格式文本中,可以使用 HTML 修饰符,例如:

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

    注释:如果文档中有到其他文件的链接,如图像文件(例如,图标或用户界面组件的图像),就应该将这些文件放到包含源文件的目录下的一个子目录 doc-files 中。javadoc 工具将从源目录将 doc-files 目录及其内容拷贝到文档目录中。在链接中需要使用 doc-files 目录,例如: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 可以用在所有文件注释的标记

    6. 包注释

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

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

    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。将抽取标记 ... 之间的所有文本。当用户长导航栏中选择 “Overview”(概览)时,就会显示出这些内容。

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

你可能感兴趣的:(Java 文档注释(学习 Java 编程语言 038))