【JAVA】javadoc —— 如何生成标准的 Java API 文档

---

一、什么是 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 插件：

  
    
      org.apache.maven.plugins
      maven-javadoc-plugin
      3.4.0
      
        
          attach-javadocs
          
            jar
          
        
      
      
        1.8
        UTF-8
        private
        true
        true
      
    
  

执行命令：

mvn javadoc:javadoc

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

---

四、javadoc 文档结构

生成的 HTML 文档包含：

• 类和接口的详细说明

• 构造方法、字段和方法的说明

• 继承关系和实现关系图示

• 索引、包说明和用例等导航页面

---

五、实用建议

• 注释写详尽，尤其是公共 API。

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

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

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

---

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