文档注释
JDK中包含一个叫做javadoc的工具，可以由源文件生成一个HTML文档。若在源代码中添加以特殊定界符/**开始的注释，也可以很容易的生成一个看上去比较专业的文档。这种方法的好处在于，将代码和注释放在一个地方，在修改源码的同时，重新运行javadoc就可以轻松的保持两者的一致性。
注释的插入
javadoc实用工具从模块，包，公共类与接口，公共的和受保护的字段，公共的和受保护的构造器及方法中抽取信息。
可以为上面各个特性编写注释，注释放置在所描述特性的前面，注释将以/*开始，且以/结束。
每个/*…/文档注释包含标记以及之后紧跟着的自由格式文本。标记以@开始，比如@since或@param。
自由格式文本的第一句应该是一个概要性的句子，javadoc工具自动的将这些句子抽取出来生成概要页。
在自由格式文本中，可以使用HTML修饰符 例：
用于强调的<em>...</em>
着重强调的<strong>...</strong>
用于项目符号列表的<ul>/<li>
及用于包含图像的<img ...>等
如要键入宽代码，需使用{@code ... }而非<code>...</code>。这样就不用操心对代码中的<进行字符转义了。类注释
类注释必须要放在import语句之后和类定义之前。
我们举一个例子
/**
* A {@code Card} object represents a playing card,such
* as "Queen of Hearts". A card has a suit (Diamond , He
* art, Spade or Club) and a value
*/
public class Card
{
...
}事实上没必要在每行的开始都添加星号，不过大部分的IDE会自动提供星号，而且换行改变时，还会重新放置星号。
方法注释
每个方法的注释都要放在所描述方法之前。除了通用标记之外，还可用下列标记：
@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;
}字段注释
只需对公共字段（通常为静态变量）建立文档。如：
/**
* The "Hearts" card suit
*/
public static final int HEARTS = 1;通用注释
标记@since text将会建立一个“since”条目。text是可以引入这个特性的版本的任何描述。 例如，@since 1.7.1 。
下面的标记可以用在类文档的注释中：
@author name
此标记将产生一个“author”条目。可以使用多个@author标记，每个@author标记就对应了一个作者。
@version text
此标记将产生一个版本条目，这里的文本可以是对当前版本的任何描述。
通过@see和@link的标记，可以使用超链接，链接到javadoc的相关部分以及外部文档。
标记@see reference将在“see also”（参见）部分增加一个超链接。它可以用于类中，也可以用于方法中。这里的reference有下面三个选择：
package.class#feature label
<a href="...">label</a>
"text"我们用第一种情况举一个例子。
@see com.horstmann.corejava.Employee#raiseSalary(double)
这样我们就建立了一个到com.horstmann.corejava.Employee的raiseSalary(double)方法的超链接。在此处可以省略报名，甚至是报名和类名都省去，省去后就会位于当前的包或者类中。需要注意一定要使用井号（#）而非（.）来分割类名和方法名，或者类名和变量名。Java编译器自身可以熟练的确定句点在分隔包、子包、类、内部类与方法和变量时的不同含义。但是javadoc没有这么聪明，需要用#对他提供帮助。
在第二种情况下，如果@see标记之后有一个<字符，那么就需要指定一个超链接，可以链接到任何URL。例如
@see <a href="www.horstmann.com/corejava.html">The Core Java home page</a>在上述情况下，都可以指定一个label（标签）作为链接锚（link anchor）。若省略了标签，则用户看到的锚就是目标代码名或者URL。
在第三种情况下，如果@see后有一个双引号（“）字符，文本就会显示在”see also“部分。例如：
@see "Core Java 2 volume 2"可以为一个特性添加多个@see标记，但必须把它们放在一起。
如果你愿意，可以在文档注释中的任何位置放置指向其他类或方法的超链接。可以在注释中任何位置插入一个形式如下的特殊标记：
{@link package.class#feature label}包注释
可以直接将类、方法和变量的注释放在Java源文件中，是要用/*…/文档注释界定就可以。但是要产生包注释就需要在每一个包目录中添加一个单独的文件。可以有如下两种选择：
1.提供一个名为package-info.java的Java文件。这个文件须包含一个初始的以/*和/界定的javadoc注释。后面是一个package语句。它不能包含更多的代码和注释。
2.提供一个名为package.html的HTML文件。会抽取标记...间的所有文本。
注释提取
在此，如果你希望HTML文件将放在名为docDirectory的目录下，执行如下步骤：
1.切换到包含你想要生成文档的源文件的目录。如果有嵌套的包想要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录。
2.如果是一个包，则运行如下命令：
javadoc -d docDirectory nameOfPackage
或者，如果要为多个包生成文档，运行：
javadoc -d docDirectory nameOfPackage1 nameOfPackage2 …
若文件处于无名的包中，则运行：
javadoc -d docDirectory *.java
如若在上述操作中省略了 -d docDirectory选项，那么HTML文件就会被提取到当前目录下，这样的结果就是可能比较混乱。
