Javadoc

Javadoc（最初是JavaDoc）^[1]是由Sun Microsystems为Java语言（现在由甲骨文公司拥有）创建的文档生成器，用于从Java源代码生成HTML格式的API文档，HTML格式用于增加将相关文档链接在一起的便利性。^[2]

Javadoc使用的“doc comments”格式^[3] 是记录Java类的事实上的行业标准。一些IDE，^[4]如IntelliJ IDEA、NetBeans和Eclipse，可以自动生成Javadoc HTML。许多文件编辑器帮助用户生成Javadoc源代码并使用Javadoc信息作为程序员的内部引用。

Javadoc还提供了用于创建doclet和taglet的API，允许用户分析Java应用程序的结构，这就是JDiff如何生成两个API版本之间发生变化的报告。

Javadoc不影响Java中的性能，因为在编译时会删除所有注释。编写注释和Javadoc是为了更好地理解代码，从而更好地维护代码。

历史

Javadoc是早期的Java语言文档生成器。^[5]在使用文档生成器之前，习惯上由专业的技术编写者编辑文档，他们通常只编写软件的独立文档，^[6]但要使这些文档与软件本身保持同步要困难得多。

自第一个版本以来，Java一直使用Javadoc，并且通常在Java开发工具包的每个新版本上都会更新。

技术架构

Javadoc注释结构

通过标准多行注释标记/* and */从代码中引发Javadoc注释。起始标记（称为开始 - 注释分隔符）具有额外的星号，如/**中所示。

第一段是对所记录方法的描述。
在描述之后是不同数量的描述性标签，表示：
1. 方法的参数（@param）
2. 方法返回的内容（@return）
3. 方法可能抛出的任何异常（@exception）
4. 其他不太常见的标签，如 @see （“另见”标签）

Javadoc概览

编写文档注释的基本结构是将它们嵌入到/**.中。Javadoc写在项目旁边，没有任何分隔换行符。请注意，任何import语句必须在类声明之前。类声明通常包括：

// import statements

/**
 * @author     姓名  <address @ example.com>
 * @version    1.6   （程序的当前版本号）
 * @since       1.2    （加入该类时程序的版本号）
 */
public class Test {
    // class body
}

对于方法，有如（1）所示的简洁的一行描述来解释项目的作用；接下来是（2）所示的更长的描述，该描述可以跨越多个段落并且是可有可无的；最后，第（3）部分列出接受的输入参数和方法的返回值。所有的Javadoc都被视为HTML，因此多个段落部分由"<p>"段落符号分隔。

/**
 * 简短的单行描述。                                                  （1）
 * <p>
 * 更长一些的描述可以写在这里。                              （2）
 * </p>
 * 在HTML段落分隔的连续段落中还可以有更多注释。
 *
 * @param  variable 描述文本。                               （3）
 * @return  描述文本。
 */
public int methodName (...) {
    // method body with a return statement
}

与方法类似的注释也可以用于变量的注释，但省略了第（3）部分，这里只包含了对变量的简短描述：

/**
 * 对变量的描述。
 */
private int debug = 0;

请注意，不建议^[7]在单个文档注释中定义多个变量。这是因为Javadoc读取每个变量并将它们分别放置到生成的HTML页面，其中包含为所有字段复制的相同文档注释。

/**
 * 点对 (x,y) 的水平和垂直距离
 */
public int x, y;      // 避免这样的做法

相反，建议分别声明和注释每个变量：

/**
 * 点的水平距离。
 */
public int x;

/**
 * 点的垂直距离。
 */
public int y;

Javadoc标签表

一部分可用的Javadoc标签^[8]列在下表中：

标签&参数	用途	适用于	引入版本
@author John Smith	描述作者。	类、接口、枚举
{@docRoot}	表示从任何生成的页面生成的文档的根目录的相对路径。	类、接口、枚举、成员、方法
@version 版本	提供软件版本，每个类或接口最多一个。	类、接口、枚举
@since 起始	描述此功能首次存在的时间。	类、接口、枚举、成员、方法
@see 参考	提供指向其他文档元素的链接。	类、接口、枚举、成员、方法
@param 名称描述	描述方法的一个参数。	方法
@return 描述	描述返回值。	方法
@exception 类描述 @throws 类描述	描述可能从此方法抛出的异常。	方法
@deprecated 描述	描述一个过时的方法。	类、接口、枚举、成员、方法
{@inheritDoc}	从被覆盖的方法复制描述。	覆盖方法	1.4.0
{@link `参考`}	链接到其他符号。	类、接口、枚举、成员、方法
{@linkplain `参考`}	与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。	类、接口、枚举、成员、方法
{@value #STATIC_FIELD}	返回静态成员的值。	静态成员	1.4.0
{@code 文本}	在代码字体中格式化文字文本，等同于<code> {@literal} </code>。	类、接口、枚举、成员、方法	1.5.0
{@literal 文本}	表示文本，随附的文本被解释为不包含HTML标记或嵌套的javadoc标记。	类、接口、枚举、成员、方法	1.5.0
{@serial 文本}	在Javadoc注释中用于默认的可序列化字段。	成员
{@serialData 文本}	记录writeObject()或writeExternal()方法写入的数据。	成员、方法
{@serialField 文本}	记录ObjectStreamField组件。	成员

示例

下面是注释一个方法的Javadoc示例。

/**
 * 验证一步象棋的移动是否可行。
 *
 * <p>使用 {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} 方法来移动棋子。
 *
 * @param theFromFile 被移动棋子的来源行
 * @param theFromRank 被移动棋子的来源列
 * @param theToFile  被移动棋子的目标行
 * @param theToRank  被移动棋子的目标列
 * @return            如果移动是可行的则返回true，否则返回false
 * @since             1.0
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    // ...body
}

/**
 * 移动一个棋子。
 *
 * @see java.math.RoundingMode
 */
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
    // ...body
}