一、什么是 javadoc？

javadoc 是 Java 官方自带的文档生成工具，通过解析源代码中的特定注释格式，自动生成标准化的 HTML 格式 API 文档，方便开发者和用户阅读。

二、javadoc 注释格式

javadoc 注释写在类、方法、字段的定义前，格式如下：

/**
 * 这是类的描述
 *
 * @author 作者名
 * @version 版本号
 */
public class MyClass {

    /**
     * 这是一个示例方法，功能是计算两个数的和
     *
     * @param a 第一个加数
     * @param b 第二个加数
     * @return 返回 a 和 b 的和
     */
    public int add(int a, int b) {
        return a + b;
    }
}

常用标签说明：

标签说明
@param方法参数说明
@return方法返回值说明
@throws抛出异常说明
@author作者
@version版本号
@see相关链接

三、使用 javadoc 生成 API 文档

1. 命令行方式

假设你的源码目录是 src，生成文档输出目录是 docs，执行：

javadoc -d docs -encoding UTF-8 -charset UTF-8 -author -version src/**/*.java

参数说明：

  • -d docs：指定生成文档的输出目录
  • -encoding UTF-8：源文件编码
  • -charset UTF-8：生成文档的字符集
  • -author：显示作者标签
  • -version：显示版本标签
  • src/**/*.java：需要生成文档的源码文件路径（根据实际项目调整）

2. 在 IntelliJ IDEA 中生成 javadoc

  1. 打开项目。
  2. 菜单栏选择：Tools -> Generate JavaDoc...。
  3. 设置输出目录，比如 docs。
  4. 选择需要生成文档的模块或包。
  5. 额外参数输入（可选）：如 -author -version。
  6. 点击 OK，等待生成完成。

3. 在 Maven 项目中集成 javadoc

在 pom.xml 中配置 Maven 插件：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.4.0</version>
      <executions>
        <execution>
          <id>attach-javadocs</id>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <source>1.8</source>
        <encoding>UTF-8</encoding>
        <show>private</show>
        <author>true</author>
        <version>true</version>
      </configuration>
    </plugin>
  </plugins>
</build>

执行命令：

mvn javadoc:javadoc

生成的文档默认在 target/site/apidocs。

四、javadoc 文档结构

生成的 HTML 文档包含：

  • 类和接口的详细说明
  • 构造方法、字段和方法的说明
  • 继承关系和实现关系图示
  • 索引、包说明和用例等导航页面

五、实用建议

  • 注释写详尽，尤其是公共 API。
  • 保持注释与代码同步，避免文档失效。
  • 适当使用标签提升文档可读性。
  • 定期生成并发布文档，便于团队协作和维护。

如果需要，我可以帮你写：

  • javadoc 高级用法和自定义样式
  • 如何生成多语言 javadoc 文档
  • 集成 javadoc 到 CI/CD 流水线

随时告诉我！