Java 文档注释生成 HTML 文档完整流程-java教程-PHP中文网

javadoc工具通过解析以/*开头、/结尾的文档注释生成html api文档，需确保注释规范、类路径正确、命令参数合理。

java 文档注释生成 html 文档完整流程

Java 文档注释（即 Javadoc）生成 HTML 文档的过程，本质是用 javadoc 工具解析源码中的特殊注释块，并按规范输出可浏览的 API 文档。核心在于注释格式正确、类路径清晰、命令参数合理。

一、确保源码中包含规范的文档注释

只有以 /** 开头、*/ 结尾的注释才会被 javadoc 工具识别为文档注释。需为公共类、方法、字段、构造器等添加描述，并合理使用标准标签：

@param 描述方法参数（仅用于方法和构造器）
@return 描述返回值（仅用于有返回值的方法）
@throws 或 @exception 说明抛出的异常
@see 添加相关类或方法的交叉引用
@since 标明引入版本
@deprecated 标记已弃用项，并建议替代方案

示例：

/**
 * 计算两个整数的和。
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和
 * @since 1.0
 * @see java.lang.Math#addExact(int, int)
 */
public static int add(int a, int b) {
    return a + b;
}

二、准备编译环境与类路径

javadoc 不要求源码已编译，但若代码依赖外部库（如 slf4j、spring-core），需通过 -classpath 指定这些 JAR 或 class 目录，否则可能报“cannot find symbol”错误。同时，确保 JDK 的 bin 目录在系统 PATH 中，或直接调用完整路径（如 $JAVA_HOME/bin/javadoc）。

常见做法：

OpenJDK 24

下载

在项目根目录下执行命令（便于统一管理源码路径）
将第三方依赖 JAR 放入 lib/ 目录，用 -classpath lib/\*.jar（Windows）或 -classpath "lib/*.jar"（Linux/macOS）引入
若使用模块化（Java 9+），可能需要额外添加 --module-path 和 --add-modules

三、执行 javadoc 命令生成 HTML

基础命令结构如下（以 Maven 项目为例，源码位于 src/main/java）：

javadoc -d docs/api \
        -sourcepath src/main/java \
        -subpackages com.example.myapp \
        -encoding UTF-8 \
        -docencoding UTF-8 \
        -charset UTF-8 \
        -windowtitle "MyApp API" \
        -doctitle "MyApp API Documentation" \
        -header "<b>MyApp</b>" \
        -use \
        -version \
        -author

关键参数说明：