baeldung 2024-05-11
1. 概述
良好的 API 文档是决定软件项目整体成功的重要因素之一。
幸运的是，所有现代版本的 JDK 都提供了 Javadoc 工具，可以从源代码中的注释自动生成 API 文档。
前提条件：
- JDK 1.4（推荐使用 JDK 7 或更高版本，以兼容最新版的 Maven Javadoc 插件）
- 将 JDK 的
/bin目录添加到PATH环境变量中 - （可选）配备内置工具的集成开发环境（IDE）
2. Javadoc 注释
我们从注释开始说起。
Javadoc 注释的结构看起来与普通的多行注释非常相似，但关键区别在于开头多了一个星号：
// 这是一行单行注释
/*
* 这是一个普通的多行注释
*/
/**
* 这是一个 Javadoc 注释
*/
Javadoc 风格的注释可以包含 HTML 标签。
2.1 Javadoc 格式
Javadoc 注释可以放在任何需要文档化的类、方法或字段上方。
这些注释通常由两个部分组成：
- 对所注释内容的描述
- 独立的块标签（以 “@” 符号开头），用于描述特定的元数据
在示例中，我们将使用一些常见的块标签。完整的块标签列表请参阅官方参考指南。
2.2 类级别的 Javadoc
让我们看看一个类级别的 Javadoc 注释是什么样子：
/**
* Hero 是我们将要使用的主要实体……
*
* 请参见 {@link com.msm.javadoc.Person} 类以了解真实身份。
* @author 美国队长
*/
public class SuperHero extends Person {
// 字段和方法
}
这里包含一个简短的描述以及两种不同类型的块标签：独立标签和内联标签：
- 独立标签 出现在描述之后，标签作为一行的第一个词，例如
@author - 内联标签 可以出现在任意位置，并用大括号包围，例如描述中的
@link标签
在本例中，我们还看到了两种块标签的用法：
{@link}提供对源代码中引用部分的内联链接@author表示添加该类、方法或字段的作者姓名
2.3 字段级别的 Javadoc
我们也可以在 SuperHero 类内部使用不带任何块标签的描述：
/**
* 英雄广为人知的公开名称
*/
private String heroName;
除非显式地向 Javadoc 命令传递 -private 选项，否则不会为私有字段生成 Javadoc。
2.4 方法级别的 Javadoc
方法可以包含多种 Javadoc 块标签。
让我们看一下下面这个方法：
/**
* <p>这是对该方法的简单描述……
* <a href="http://www.supermanisthegreatest.com">超人！</a>
* </p>
* @param incomingDamage 所受到的伤害值
* @return 英雄在攻击后剩余的生命值
* @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
* @since 1.0
*/
public int successfullyAttacked(int incomingDamage) {
// 具体实现
return 0;
}
successfullyAttacked 方法既包含描述，也包含多个独立的块标签。
Javadoc 提供了大量块标签来帮助生成完善的文档，我们可以包含各种信息，甚至可以在注释中使用基本的 HTML 标签。
下面我们回顾一下上面示例中遇到的标签：
@param：提供关于方法参数的有用描述@return：描述方法将返回或可能返回的内容@see：生成类似于{@link}的链接，但更侧重于作为参考资料而非内联使用@since：指定该类、字段或方法是在哪个版本中加入项目的@version：指定软件版本，通常与%I%和%G%宏一起使用@throws：进一步说明在哪些情况下会抛出异常@deprecated：解释为何弃用某段代码、何时弃用，以及替代方案是什么
虽然这两个部分在技术上都是可选的，但至少需要提供其中之一，Javadoc 工具才能生成有意义的内容。
3. Javadoc 生成
为了生成 Javadoc 页面，我们需要了解 JDK 自带的命令行工具以及 Maven 插件。
3.1 Javadoc 命令行工具
Javadoc 命令行工具功能强大，但也相对复杂。
如果直接运行 javadoc 命令而不带任何选项或参数，将会报错并输出它期望的参数列表。
我们至少需要指定要为其生成文档的包或类。
打开命令行并导航到项目目录。假设所有类都位于项目目录下的 src 文件夹中：
user@msm:~$ javadoc -d doc src\*
这将在名为 doc 的目录中生成文档（通过 -d 参数指定）。如果存在多个包或文件，则需要全部列出。
当然，使用具备内置功能的 IDE 会更加简便，通常也更推荐这种方式。
3.2 使用 Maven Javadoc 插件
我们也可以使用 Maven Javadoc 插件：
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.2</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
<tags>
...
</tags>
</plugin>
</plugins>
</build>
在项目根目录下，运行以下命令即可在 target/site 目录中生成 Javadoc：
user@msm:~$ mvn javadoc:javadoc
Maven 插件功能非常强大，能够无缝处理复杂的文档生成任务。
可以看到 SuperHero 类继承关系的树状视图，以及我们的描述、字段和方法，还可以点击链接查看更多信息。
3.3 自定义 Javadoc 标签
除了使用预定义的块标签外，我们还可以创建自定义块标签。只需在 Javadoc 命令行中使用 -tag 选项，格式为 <标签名>:<允许的位置>:<标题>。
例如，若要创建一个名为 @location 的自定义标签（允许在任意位置使用），并在生成的文档中显示为“Notable Locations”（著名地点）标题，可以运行如下命令：
user@msm:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*
然后在 Javadoc 注释的块部分使用该标签：
/**
* 这是一个示例……
* @location 纽约
* @returns blah blah
*/
Maven Javadoc 插件也足够灵活，允许我们在 pom.xml 中定义自定义标签。
为了在项目中设置上述相同的标签，可以在插件的 <tags> 部分添加如下配置：
...
<tags>
<tag>
<name>location</name>
<placement>a</placement>
<head>Notable Places:</head>
</tag>
</tags>
...
这样就可以一次性定义自定义标签，而无需每次重复指定。
4. 结论
在本文中，我们简要介绍了如何编写基本的 Javadoc 注释，并使用 Javadoc 命令行工具生成文档。
更简便的方式是使用 IDE 内置的生成功能，或将 Maven 插件集成到 pom.xml 文件中并运行相应命令。