Java知识点——文档注释

JDK 包含一个很有用的工具，叫做javadoc, 它可以由源文件生成一个 HTML 文档。联机 API 文档就是通过对标准 Java 类库的源代码运行 javadoc 生成的。如果在源代码中添加以专用的定界符 /**开始的注释，那么可以很容易地生成一个文档。这种方式可以将代码与注释保存在一个地方，所以在修改源代码的同时，重新运行 javadoc 就可以轻而易举地保持两者的一致性。

注释的插入

javadoc 实用程序（utility) 从下面几个特性中抽取信息：

包
公有类与接口
公有的和受保护的构造器及方法
公有的和受保护的域

注释应该放置在所描述特性的前面。注释以 /**开始，并以 */ 结束。 每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本（ free-form text )。标记由 @开始，如@author 或@param。自由格式文本的第一句应该是一个概要性的句子。javadoc 自动地将这些句子抽取出来形成概要页。在自由格式文本中，可以使用 HTML 修饰符，例如，用于强调的 <em>...</eitf>、用于着重强调的 <strong>...</stroiig> 以及包含图像的 <img ...> 等。若要键入等宽代码，需使用 {@code ... } 而不是<code>...</code>。

类注释

类注释必须放在 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
{
	...
}

方法注释

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

@param 变量描述
这个标记将对当前方法的“ param” （参数）部分添加一个条目。这个描述可以占据多行，并可以使用HTML 标记。一个方法的所有 @param 标记必须放在一起。
@return 描述
这个标记将对当前方法添加“ return” （返回）部分。这个描述可以跨越多行，并可以使用 HTML 标记。
©throws 类描述
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。

下面是一个方法注释的示例：

/**
* 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;
}

域注释

只需要对公有域（通常指的是静态常量）建立文档。例如,

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

通用注释

下面的标记可以用在类文档的注释中。

@author 姓名
这个标记将产生一个 “author” (作者）条目。可以使用多个 @author 标记，每个 @author 标记对应一个作者
@version
这个标记将产生一个“ version”（版本）条目。这里的文本可以是对当前版本的任何描述。

下面的标记可以用于所有的文档注释中。

@since 文本
这个标记将产生一个“ since” （始于）条目。这里的 text 可以是对引人特性的版本描述。例如，@since version 1.7.1。
@deprecated 文本
这个标记将对类、方法或变量添加一个不再使用的注释。
@see 引用
这个标记将在“ see also” 部分增加一个超级链接。它可以用于类中，也可以用于方法中。

包与概述注释

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

提供一个以 package.html 命名的 HTML 文件。在标记 <body>...</body> 之间的所有文本都会被抽取出来。
提供一个以 package-info.java 命名的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的 Javadoc 注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。

还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为 overview.html 的文件中，这个文件位于包含所有源文件的父目录中。标记 <body>... </body> 之间的所有文本将被抽取出来。当用户从导航栏中选择“ Overview” 时，就会显示出这些注释内容。

注释的抽取

这里，假设 HTML 文件将被存放在目录 docDirectory 下。执行以下步骤：

切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如 com. horstmann.corejava,就必须切换到包含子目录 com 的目录（如果存在 overview.html 文件的话，这也是它的所在目录)。

如果是一个包，应该运行命令:

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.eom/:javase/8/docs/api *.java

那么，所有的标准类库类都会自动地链接到 Oracle 网站的文档。如果使用 -linksource 选项，则每个源文件被转换为 HTML (不对代码着色，但包含行编号)，并且每个类和方法名将转变为指向源代码的超链接。有关其他的选项，请查阅 javadoc 实用程序的联机文档，http://docs.orade.com/javase /8/docs/guides/javadoc。