Javadoc
为代码编写文档，最大的问题可能就是对文档的维护了。如果文档和代码是分离的，那么每次更新代码就必须更新文档。解决方法就是将代码和文档关联起来，最简单的就是将所有东西都放在同一个文件中。不过，要完成这个构想，就需要特殊的注释语法来为文档打上标签，以及一个专门的工具，来将这些注释提取出来并转换为某种有用的格式。
这个提取注释的工具称为 Javadoc，安装 JDK 就可以获得。它使用了 Java 编译器的某些技术来寻找特殊的注释标签。除了提取出用这些标签标记的信息外，它还会拉取紧挨注释的类名或方法名。通过这种方式，你可以用最少的工作量生成优雅的程序文档。
Javadoc 的输出是 HTML 文件，可用 Web 浏览器查看。
此外，以编写称为 doclet 的自定义 Javadoc 处理程序，用来对 Javadoc 所处理的信息执行特殊操作（例如生成不同格式的输出）。
接下来对 Javadoc 进行基本介绍以及概述，可以在 JDK 文档中查看更详细的描述。
语法
所有的 Javadoc 指令都出现在以 /** 开头的注释内（以 */ 结束)。 Javadoc 有两种主要的使用方式：一是嵌入式 HTML，二是使用“doc 标签”。独立 doc 标签是以 @ 开头的指令，放在一行注释的开头（开头的 * 会被忽略）。行内 doc 标签可以出现在 Javadoc 注释内的任何地方，同样以 @ 开头，但必须用花括号围起来。
一共有三种类型的注释文档，分别对应于注释前面的元素：类、字段和方法。如下：
/** 类的注释 */
public class Documentation1 {
/** 字段的注释 */
public int i;
/** 方法的注释 */
public void f() {}
}Javadoc 只会为有 public 和 protected 权限的成员处理注释文档。private 和包权限成员的注释默认会被忽略。这很合理，因为以调用方程序员的视角来看，只有 public 和 protected 权限的成员在文件外是可用的。可以使用 -private 标志将 private 成员也纳入处理范围。
用以下代码通过 Javadoc 处理：
这会生成一组 HTML 文件。如果在浏览器中打开 index.html，就会看到结果和所有其他的 Java 文档具有相同的标准格式，因此使用者可以很轻松地浏览各个类。
嵌入式 HTML
Javadoc 会将 HTML 代码原样传给生成的 HTML 文档。这使你可以充分地使用 HTML，不过主要目的是为了格式化代码，例如:
也可以像在其他任何 Web 文档中那样，使用 HTML 来格式化描述中的常规文本：
注意，在文档注释中，行首的星号和空格会被 Javadoc 丢弃。Javadoc 会重新格式化所有内容，使其符合标准的文档外观。不要使用诸如 <h1> 或 <hr>之类的标题来作为嵌入式 HTML，因为 Javadoc 会插入自己的标题，这样两者就冲突了。
所有类型的注释文档（类、字段和方法）都可以支持嵌入式 HTML。
部分示例标签
下面是一些可用于代码文档的 Java 标签。在正式尝试使用 Javadoc 之前，请认真查阅 JDK 文档中对 Javadoc 的说明，了解 Javadoc 的所有使用方式。
@see
该标签用于引用其他类中的文档。Javadoc 会生成通过 @see 标签超链接到其他文档的 HTML。
每个 @see 都会向生成的文档中增加一个 "See Also"（另请参阅...）超链接入口 Javadoc 不会验证该超链接是否可用。
{@link package.class# member label}
和 @see 非常相似，只不过还可以用在行内（@see 必须用在行首，{@link} 则无次限制），并且使用 label 作为超链接文本，而不是 "See Alse"。
{@docRoot}
生成相对文档根目录的相对路径。在显式超链接到文档树中的页面时很有用。
{@inheritDoc}
将文档从当前类最近的基类继承到当前的文档注释中。
@version
其中 version-information（版本信息）是你认为适合引入的任意重要信息。如果在 Javadoc 命令行中使用 -version 标志，会在生成的 HTML 文档中专门调出版本信息。
@author
如果在 Javadoc 命令行中使用 -author 标签，会在生成的 HTML 文档中专门调出作者信息。
可以使用多个作者标签来表示一组作者，但是必须将其连续排列。在生成的 HTML 中，所有的作者信息都会被集中放在一个段落里。
@since
此标签表示本代码是从哪个版本开始使用某个特定功能的。例如，它会出现在 HTML 的 Java 文档中，表示某功能首次出现的 JDK 版本。
@param
该标签会为方法参数生成文档：
其中 parameter-name（参数名）是方法参数列表中的标识符，description（描述）则是可以继续在后面的行中显示的文本。此描述文本在遇到一个新的文档标签时即被认为结束。该标签的使用数量没有限制，通常每个参数用一个。
@return
此标签会记录返回值：
其中 description 用于表示返回值的意义。它支持换行。
@throws
方法可以产生任意数量的不同类型的异常，这些异常都需要描述。异常标签的形式如下：
其中 fully-qualified-class-name（完整的合格类名）用于为异常类提供一个明确的名字，description（支持换行）则会告诉你为什么该类型的异常会在方法调用中出现。
@deprecated
此标签表示该功能已被改进后的功能取代。deprecated（弃用）标签建议你不要继续使用该功能，因为它可能会在未来某个时候被移除。如果调用了被标记为 @deprecated 的方法，会导致编译器产生警告。在 Java 5 中，Javadoc 标签 @deprecated 被 @Deprecated 注解取代了。
文档示例
你可以在 Java 标准库的源代码中找到 Javadoc 注释文档的很多例子。