4.9   文档注释

JDK包含一个很有用的工具，叫做javadoc，它可以由源文件生成一个HTML文档。事实上，在第3章讲述的联机API 文档就是通过对标准Java类库的源代码运行javadoc生成的。

如果在源代码中添加以专用的定界符/**开始的注释，那么可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存入一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行javadoc就可以轻而易举地保持两者的一致性。

4.9.1   注释的插入

javadoc实用程序（utility）从下面几个特性中抽取信息：

包

公有类与接口

公有的和受保护的方法

公有的和受保护的域

在第5章中将介绍受保护特性，在第6章将介绍接口。

应该为上面几部分编写注释。注释应该放置在所描述特性的前面。注释以 /** 开始，并以 */ 结束。

每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本（free-form text）。标记由 @ 开始，如@author或@param。

自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动地将这些句子抽取出来形成概要页。

在自由格式文本中，可以使用HTML修饰符，例如，用于强调的 ...、用于设置等宽“打字机”字体的 ...、用于着重强调的 ... 以及包含图像的等。不过，一定不要使用