原文
4.10文档注释
JDK 包含一个很有用的工具，叫作 javadoc，它可以由源文件生成一个HTML文档。事实上，在第 3 章介绍的联机API文档就是通过对标准 Java 类库的源代码运行 javadoc 生成的。如果在源代码中添加以特殊定界符 /** 开始的注释，那么你也可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方法，因为这样可以将代码与注释放在一个地方。应该知道，如果将文档存放在一个单独的文件中，随着时间的推移，代码和注释很可能出现不一致。不过，如果文档注释与源代码在同一个文件中，就可以很容易地同时修改源代码和注释，然后重新运行 javadoc。
4.10.1注释的插入
javadoc 实用工具从下面几项中抽取信息:
-
模块;
-
包;
-
公共类与接口;
-
公共的和受保护的字段;
-
公共的和受保护的构造器及方法。
第5章中将介绍受保护特性，第 6章中将介绍接口，模块在卷2的第9章介绍。
可以(而且应该)为以上各个特性编写注释。各个注释放置在所描述特性的前面。注释以/** 开始，并以*/结束。
每个/** … */文档注释包含标记以及之后紧跟着的自由格式文本(free-form text)。标记以@开始，如@since 或 @param。
自由格式文本的第一个句子应该是一个概要陈述。javadoc 工具自动地将这些句子抽取出
来生成概要页。
在自由格式文本中，可以使用HTML 修饰符，例如用于强调<em> … </em> 、用于着重强调的<strong> … </strong>，用于项目符号列表的<ul>/<li>以及用于包含图像的<img …>等，要键入等宽代码，需要使用{@code …} 而不是<code> … </code> —— 这样一来，就不用对代码中的 < 字符转义了。