原文

4.10.6 包注释

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

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

4.10.7 注释提取

在这里，假设你希望HTML 文件将放在名为 docDirectory 的目录下。执行以下步骤:

1. 切换到源文件目录，其中包含想要生成文档的源文件。如果有嵌套的包要生成文档，例如： com.horstmann.corejava，就必须切换到包含子目录 com 的目录(如果提供 overview.html 文件的话，这就是这个文件所在的目录)。
2. 如果是一个包，应该运行命令

javadoc -d docDirectory nameOfPackage

或者，如果要为多个包生成文档，运行:

javadoc -d docDirectory nameOfPackage1 nameOfPackage ...

如果你的文件在无名包中，则应该运行:

javadoc -d docDirectony *.java

如果省略了 -d docDirectory 选项，HTML 文件就会提取列当前目录下。这样可能很混乱，因此我不提倡这种做法。

可以使用很多命令行选项对 javadoc 程序进行微调。例如，可以使用 -author 和 -version 选项在文档中包含 @author 和 @version 标记(默认情况下，这些标记会被略)。另一个很有用的选项是 -link，用来为标准类添加超链接。例如，如果使用命令

javadoc -link http://docs.oracle.com/javase/9/docs/api *.java

那么，所有的标准类库的类都会自动地链接到 Oracle 网站的文档。

如果使用 -linksource 选项，那么每个源文件将会转换为 HITML(不对代码着色，但包含行号)，并且每个类和方法名将变为指向源代码的超链接。

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

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