JDK包含一个很有用的工具，叫做javadoc，它可以由源文件生成一个HTML文档。javadoc实用程序（utility）从下面几个特性中抽取信息：
l 公有类与接口
l 公有的和受保护的方法
l 公有的和受保护的域
每个/**…*/文档注释在标记之后紧跟自由格式文本(free form text)。标记由@开始。如@auther或@param。
自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动将这些句子抽取出来形成概要页。
类注释：类注释必须放在import语句之后，类定义之前。
方法注释：每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记：
@param variable description
这个标记将对当前方法的“param”（参数）部分添加一个条目。这个描述可以占据多行，并可以使用HTML标记。一个方法的所有@param标记必须放在一起。
@return description
这个标记将对当前方法添加“return”（返回）部分。这个描述可以跨越多行，并使用HTML标记。
@throws class description
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。
域注释：只需要对公有域（通常指的是静态常量）建立文档。
通用注释：
下面的标记可以用在类文档的注释中：
@auther name
这个标记将产生一个“auther”（作者）条目，可以使用多个@auther标记，每个@auther标记对应一名作者。
@version text
这个标记将产生一个“version”（版本）条目。这里的text可以是对当前版本的任何描述。
下面的标记可以用所有的文档注释：
@since text
这个标记将产生一个“since”（始于）条目。这个的text可以是对引入特性的版本描述@since version 1.7.1
@deprecated text
这个标记将对类、方法或变量添加一个不再使用的注释。text中给出了取代的建议。
@see reference
这个标记将在“see also”部分增加一个超级链接。它可以用于类中，也可以用于方法中。
这里的reference可以选择下列情形之一：
a) package.class#featurelabel
b) <ahref=”…”>label</a>
c) “text”
第一种情况是最常见的，只要提供类、方法或变量的名字，javadoc就在文档中插入一个超链接。列如：
@seecom.horstmann.corejava.Employee#raiseSalary(double)
建立一个链接到com.horstmann.corejava.Employee类的raiseSalary(double)方法的超链接。可以省略包名，甚至把包名和类名都省去，此时，链接将定位于当前包或当前类。
需要注意，一定要使用（#）分隔类名与方法名（或类名与变量名）。
如果@see标记后面有一个双引号（“）字符，文本就会显示在”see also“部分，例如：
@see “Core Java 2 volume 2”
可以为一个特性添加多个@see标记，但必须将它们放在一起。
如果愿意的话，还可以在注释中的任何位置放置指向其他类或方法的超级链接，以及插入一个专用的标记，例如：
{@link package.class#feature label}
这里的特性描述规则与@see标记的规则一样。
包与概述注释
可以直接将类、方法和变量注释放置在Java源文件中，只要用/**…*/文档注释就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件，可以有如下两个选择：
1) 提供一个以package.html命名的HTML文件。在标记<BODY>…</BODY>之间的所有文本都会被抽取出来。
2) 提供一个以package-info.java命名的Java 文件。这个文件必须包含一个初始的以/**和*/界定的Javadoc注释，跟随在一个包语句之后，它不应该包含更多的代码或注释。
还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含源文件的父目录中，标记<BODY>…</BODY>直接的所有文本将被抽取出来。当用户从导航栏中选择“Overview”，就会显示出这些注释的内容。
注释的抽取
1) 这里，假设HTML文件将被存放在目录docDirectory下。执行以下步骤com.horstmann.corejava，就必须切换到包含子目录com的目录。
2) 如果是一个包，应该运行命令：
javadoc –d docDirectorynameofPackage
对于多个包生成文档，运行：
javadoc –d docDirectory nameofPackage1nameofPackage2 …
如果文件在默认包中，运行：
javadoc –d docDirectory *.java
如果省略了-d docDirectory选项，那么HTML文件就会被提取在当前目录下。不建议这么做！！！
