---

一、什么是 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。

• 保持注释与代码同步，避免文档失效。

• 适当使用标签提升文档可读性。

• 定期生成并发布文档，便于团队协作和维护。

---

【JAVA】javadoc，如何生成标准的JAVA API文档 – 菜鸟-创作你的创作