JDK包含一个非常有用的工具，叫做javadoc，它可以从源文件生成HTML文档。事实上，我们在第3章中描述的在线API文档仅仅是在标准Java库的源代码上运行javadoc的结果。
如果在源代码中添加以特殊分隔符/**开头的注释，也可以轻松生成专业外观的文档。这是一种非常好的方法，因为它允许您将代码和文档放在一个地方。如果您将文档放在单独的文件中，那么，正如您可能知道的，代码和注释往往会随着时间的推移而不同。当文档注释与源代码在同一个文件中时，更新和再次运行javadoc是一件容易的事情。
javadoc工具提取以下项目的信息：
模块包public类和接口public和protected域public和protected构造函数和方法第5章介绍了protected特性，第6章介绍了接口，第二卷第9章介绍了模块。
您可以（并且应该）为这些特性中的每一个提供注释。每个注释都放在它所描述的特性的正上方。注释以/**开头，以*/结尾。
每个/**…*/文档注释包含自由格式的文本，后跟标记。标记以@开头，例如@since或@param。
自由格式文本的第一句话应该是摘要语句。javadoc工具自动生成提取这些句子的摘要页。
在自由格式文本中，可以使用HTML修饰符，如<em>…</em>用于强调（斜体），<strong>…<strong>对于更强烈的强调（粗体），<ul>/<li>用于项目符号列表，以及<img.../>包含图像。要输入代码，请使用{@code…}而不是<code>…<code>-这样做您就不必担心转义代码中的<字符.
注意
如果您的注释包含指向其他文件的链接，例如图像（例如，用户界面组件的图表或图像），请将这些文件放入包含源文件的目录的子目录（命名为doc-files）中。javadoc实用程序将把doc-files目录及其内容从源目录复制到documentation目录。您需要使用链接中的doc-file目录，例如<img src="doc-files/uml.png" alt="UML diagram"/>。
类注释必须放在任何import语句之后，直接放在class定义之前。
以下是类注释的示例：
/** * 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</code> 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). */但是，大多数IDE会自动提供星号，并在换行时重新排列它们。
每个方法注释必须紧跟在它描述的方法之前。除了通用标记外，还可以使用以下标记：
@param变量描述 此标记向当前方法的“参数”部分添加一个条目。描述可以跨多行，并且可以使用HTML标记。一个方法的所有@param标记必须放在一起。@return描述 此标记向当前方法添加“返回”部分。描述可以跨多行，并且可以使用HTML标记。@throws类描述 此标记添加了一个注释，说明此方法可能引发异常。异常是第7章的主题。以下是方法注释的示例：
/** * Raises the salary of an employee. * @param byPercent the percentage by which to raise the salary * @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;标记@since文本将生成一个“since”条目。文本可以是介绍此功能的版本的任何描述。例如，@since 1.7.1。
在类文档注释中可以使用以下标记：
@author名字 此标记生成“author”条目。您可以有多个@author标记，每个作者一个。不要觉得有必要使用这个标签，你的版本控制系统会更彻底地跟踪作者。@version文本 此标记生成一个“版本”条目。文本可以是当前版本的任何描述。您可以使用指向javadoc文档其他相关部分的超链接，或者到外部文档，通过使用@see和@link标记。
标记@see引用在“see also”部分添加了一个超链接。它可以与类和方法一起使用。在这里，引用可以是以下内容之一：
package.class#feature label <a href=". . .">label</a> "text"第一种情况是最有用的。提供类、方法或变量的名称，javadoc将超链接插入到文档中。例如，
@see com.horstmann.corejava.Employee#raiseSalary(double)链接到com.horstmann.corejava.Employee类中的raiseSalary(double)方法。您可以省略包的名称，或者同时省略包和类名。然后，该特性将位于当前包或类中。
请注意，必须使用#而不是句点来将类与方法或变量名分开。Java编译器本身非常熟练地将周期字符的各种含义确定为包、子包、类、内部类和方法和变量之间的分隔符。但是javadoc实用程序并没有那么聪明，所以你必须帮助它。
如果@see标记后跟一个<字符，则需要指定一个超链接。你可以链接到任何你喜欢的网址。例如：
@see <a href="www.horstmann.com/corejava.html">The Core Java home page</a>在每一种情况下，您都可以指定一个可选标签，该标签将作为超链接显示。如果省略标签，用户将看到目标代码名或URL的超链接。
如果@see标记后跟一个"字符，则文本将显示在“see also”部分中。例如：
@see "Core Java 2 volume 2"您可以为一个功能添加多个@see标记，但必须将它们放在一起。
如果愿意，可以在任何文档注释中的任何位置放置指向其他类或方法的超链接。插入一个特殊格式的标记
{@link package.class#feature label}在注释中的任何地方。功能描述遵循与@see标记相同的规则。
最后，对于Java 9，可以使用{@index entry}标签向搜索框添加条目。
将类、方法和变量注释直接放置到Java源文件中，由/**…*/分隔文件注释。但是，要生成包注释，需要在每个包目录中添加一个单独的文件。您有两个选择：
提供一个名为package-info.java的Java文件。文件必须包含一个初始的javadoc注释，用/**和*/分隔，后跟一个package语句。它不应该包含更多的代码或注释。提供一个叫做package.html的HTML文件。所有在<body>...</body>中的标签会被提取出来。这里，docDirectory是您希望HTML文件进入的目录的名称。遵循以下步骤：
跳转到一个目录，该目录包含了你想要提取文档的源文件。如果要记录嵌套的包，例如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.com/javase/9/docs/api *.java所有标准库类都自动链接到Oracle网站上的文档。
如果使用-linksource选项，则每个源文件都将转换为HTML（不带颜色编码，但带有行号），并且每个类和方法名都将变成指向源的超链接。
还可以为所有源文件提供概述注释。将它放在overview.html等文件中，并使用命令行选项-overview filename运行javadoc工具。标签之间的所有文本<body>...</body>被提取出来了。当用户从导航栏中选择“概述”时，将显示内容。
有关其他选项，请参阅javadoc实用程序的联机文档，网址为https://docs.oracle.com/javase/9/javadoc/javadoc.htm
