当前位置：首页 > news >正文

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

news 来源：原创 2025/6/9 5:05:17

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

打开项目。
菜单栏选择：Tools -> Generate JavaDoc...。
设置输出目录，比如 docs。
选择需要生成文档的模块或包。
额外参数输入（可选）：如 -author -version。
点击 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>

执行命令：