原文

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> —— 这样一来，就不用对代码中的 < 字符转义了。

注释：如果文档中有到其他文件的链接，如图像文件(例知，图表或同户界面组件的图像)，就应该将这些文件放到包含源文件的目录下的一个子目录 doc-files 中。javadoc 工具将从源目录将 doc- flles 目录及其内容复制到文档目录中。在链接中需要使用的doc-files目录，例如 <img src="doc-files/uml.png" alt="UML diagram"/>。