Javadoc

<image>

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

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

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

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

## 历史

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

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

## 技术架构

### Javadoc注释结构

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

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

### Javadoc概览

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

```java
// import statements

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

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

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

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

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

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

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

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

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

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

### Javadoc标签表

一部分可用的Javadoc标签列在下表中：

标签&参数｜用途｜适用于｜引入版本

@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示例。

```java
/**
 * 验证一步象棋的移动是否可行。
 *
 * <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
}
```