JDK 包含一个很有用的工具，叫做 javadoc，它可以由源文件生成一个 HTML 文档。如果在源代码中添加以专用的定界符 /** 开始的注释，那么可以很容易地生成一个看上去具有专业水准的文档。
这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行 javadoc 就可以轻而易举地保持两者的一致性。
注释的插入
javadoc 实用程序（utility）从下面几个特性中抽取信息：
- 包
- 公有类与接口
- 公有的和受保护的构造器及方法
- 公有的和受保护的域
应该为上面几部分编写注释、注释应该放置在所描述特性的前面。注释以 /** 开始，并以 */ 结束。
每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本（free-form text）。标记由 @ 开始，如 @author 或 @param。
自由格式文本的第一句应该是一个概要性的句子。javadoc 实用程序自动地将这些句子抽取出来形成概要页。
在自由格式文本中，可以使用 HTML 修饰符，例如，用于强调的 <em>...</em>、用于着重强调的 <strong>...</strong> 以及包含图像的 <img ...> 等。不过，一定不要使用 <h1> 或 <hr>，因为它们会与文档的格式产生冲突。若要键入等宽代码，需使用{@code...}而不是 <code>...</code>，这样一来，就不用操心对代码中的 < 字符转义了。
类注释
类注释必须放在 import 语句之后，类定义之前。
package demo;
import static java.lang.System.out;
/**
* demo
*/
public class KnowledgeDict {
public static void main(String[] args) {
out.println("Hello World");
}
}
没有必要在每一行的开始用星号 *，例如，以下注释同样是合法的：
/**
demo
*/
public class KnowledgeDict {
public static void main(String[] args) {
out.println("Hello World");
}
}
方法的注释
每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记：
-
@param 变量描述
这个标记将对当前方法的“param”（参数）部分添加一个条目。这个描述可以占据多行，并可以使用 HTML 标记。一个方法的所有 @param 标记必须放在一起。
-
@return 描述
这个标记将对当前方法添加“return”（返回）部分。这个描述可以跨越多行，并可以使用 HTML 标记。
-
@throws 类描述
这个标记将添加一个注释，用于表示这个方法有可能抛出异常。
/**
* parseLong
*
* @param input
* @return
* @throws NumberFormatException
*/
public long parseLong(String input) throws NumberFormatException {
long l = Long.parseLong(input);
return l;
}
域注释
只需要对公有域（通常指的是静态常量）建立文档。
/**
* annotation
*/
public static final int ANNOTATION = 1;
通用注释
下面的标记可以用在类文档的注释中。
-
@author 姓名
这个标记将产生一个“author”（作者）条目。可以使用多个 @author 标记，每个 @author 标记对应一个作者。
-
@version 文本
这个标记将产生一个“version”（版本）条目。这里的文本可以是对当前版本的任何描述。下面的标记可以用于所有的文档注释中。
-
@since 文本
这个标记将产生一个“since”（始于）条目。这里的 text 可以是对引人特性的版本描述。
-
@deprecated 文本
这个标记将对类、方法或变量添加一个不再使用的注释。文本中给出了取代的建议。
-
@see 引用
这个标记将在“see also”部分增加一个超级链接。它可以用于类中，也可以用于方法中。
