JDK 包含 个很有用的工具，叫做javadoc ，它可以由源文件生成 HTML 文档。事 实上，在第 章讲述的联机 API 文档就是通过对标准 Java 类库的源代码运行javadoc 成的 如果在源代码中添加以专用的定界符／＊＊开始的注释，那么可以很容易地生成 个看上 去具有专业水准的文档 这是一种很好的方式，因为这种方式可以将代码与注释保存在一个 地方 如果将文档存入 个独立的文件中，就有可能会随着时间的推移，出现代码和注释不 致的问题 然而，由于文档注释与源代码在同 个文件中，在修改源代码的同时， 重新运 javadoc 就可以轻而易举地保持两者的一致性            注释的插入 javadoc 实用程序（utility ）从下面几个特性中抽取信息： ．包 ·公有类与接口 ·公有的和受保护的构造器及方法 ·公有的和受保护的域 在第 章中将介绍受保护特性，在第 章将介绍接口 应该为上面几部分编写注释 注释应该放置在所描述特性的前面 注释以／忡开始，并 以＊／结束 每个／＊＊ ．．． ／文档注释在标记之后紧跟着自由格式文本（ free-form text ）。 标记由 ＠开 始，如＠author 或＠param 自由格式文本的第一句应该是一个概要性的句子 javadoc 实用程序自动地将这些句子抽 取出来形成概要页 在自由格式文本中，可以使用 HT~ 修饰符，例如，用于强调的＜em>... </em 着重强调的＜ trong ... </ strong＞以及包含图像的＜img ... ＞等 不过，－定不要使用＜hl ＞或 ＞，因为它们会与文档的格式产生冲 若要键入等宽代码， 使用｛＠code ... ｝而不是 code＞…＜／code 一寸主样 来，就不用操心对代码中的＜字符转义了   注释：如果文档中有到其他文件的链接，例如，图像文件 用户界面的组件的图表或 像等），就应该将这些文件放到子目录 doc-files javadoc 实用程序将从源目录拷贝这 些目录及其中的文件到文档目录中 在链接中需妥使用 doc-files 目录，例如：＜img src “ doc-files/um!. png ” alt=“UMLdiagram ”＞ 4.9.2 类注释 类注释必须放在 import 语句之后，类定义之前  

 

 

方法注释 每一个方法注释必须放在所描述的方法之前 除了通用标记之外，还可以使用下面的标记： • @param 描述 这个标记将对当前方法的“ param ”（参数）部分添加一个条目 这个描述可以占据多 行，并可以使用 HTML 标记。一个方法的所有＠param 标记必须放在 • @return 描述 这个标记将对当前方法添加“ return ”（返回）部分 这个描述可以跨越多行，井可以 使用 HTML 标记 • @throws 描述 这个标记将添加 个注释，用于表示这个方法有可能抛出异常 有关异常的详细内容 将在第 10 中讨论 下面是 个方法注释的示例：    

 

 

域注释 只需要对公有域（通常指的是静态常量）建立文档 例如，