JDK 包含一个很有用的工具，叫做 javadoc，它可以由源文件生成一个 HTML 文档。事实上，联机 API 文档就是通过对标准 Java 类库的源代码运行 javadoc 生成的。
在源代码中写上注释，是一种非常好的方式，通过 javadoc，你可以将代码和注释保存在一个地方，这对后续的维护提供了很大的遍历，比如，在修改源代码之后，就可以直接修改代码上的注释使其同步。然后使用 javadoc 来生成最新的文档。

注释的插入

javadoc 会从下面几个特性中抽取信息：

  • 包
  • 共有类与接口
  • 公有的和受保护的构造器及方法
  • 共有的和受保护的域

再写注释的过程中，注释应该放在描述特性的前面。注释以 / 开始，以 */ 结束。
每个 /…/ 文档注释在标记之后紧跟着自由格式文本（free-form text）。标记由 @ 开始，如 author 或 @param。
自由格式文本的第一句应该是一个概要性的句子。javadoc 实用程序自动地将这些句子抽取出来形成概要页。
在自由格式文本中，*可以使用 HTML 修饰符，例如，用于强调的 <em>...</em>、用于着重强调的 <strong>...</strong> 以及包含图像的 <img...> 等。不过，一定不要使用 <h1> 或 <hr>，因为它们会与文档的格式产生冲突。若要键入等宽代码，需使用 {@code...} 而不是 <code>...</code> 这样一来，就不用操心对代码中的<字符转义了。

如果文档中有到其他文件的链接，例如，图像文件（用户界面的组件的图表或图像等），就应该将这些文件放到子目录 doc-files 中。javadoc 实用程序将从源目录拷贝这些目录及其中的文件到文档目录中。在链接中需要使用 doc-files 目录，例如：9.文档注释 - 图1。

一些注释

  • parma 变量描述
  • return 返回值描述
  • throws 异常描述
  • author 作者姓名，可以使用多个 author 标记
  • version 版本
  • since 从哪个版本开始
  • deprecated 过时的方法
  • see 引用超链接或类、方法和变量

    javadoc 命令

    假设你有这样的目录结构： ``` . ├── docDirectory └── src └── com
    1.   ├── mycompany
    2.   │   └── PayrollApp.java
    3.   └── yikang
    4.       └── corejava
    5.           └── Employee.java
  1. 我想在 docDirecoty 目录下存放文档。你可以运行这个命令来生成文档：

[src] $ javadoc -d ../docDirectory com.mycompany com.yikang.corejava

  1. 注意，上述是在 src 目录下执行的命令。上述会在生成 com.mycompany 和 com.yikang.corejava 两个包的文档。<br />如果文件在默认包中，就可以运行：

$ javadoc -d ../docDirectory *.java

`` 如果省略了-d docDirecoty` ，HTML 文件就会提取到当前目录下，会造成混乱。
更多详细，请参考 Wiki