Javadoc工具通过解析以/*开头、/结尾的文档注释生成HTML API文档，需确保注释规范、类路径正确、命令参数合理。
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）。
立即学习“Java免费学习笔记（深入）”；
常见做法：
- 在项目根目录下执行命令（便于统一管理源码路径）
- 将第三方依赖 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
关键参数说明：
-
-d docs/api：指定输出目录（会自动创建） -
-sourcepath：声明源码根路径（不是单个 .java 文件） -
-subpackages：递归处理指定包及其子包下的所有 public 类 -
-encoding / -docencoding / -charset：统一设为 UTF-8，避免中文乱码 -
-use：生成“已使用该类的类”等关联页面 -
-version和-author：分别启用@version和@author标签解析
如只需生成某几个类的文档，可直接列出全限定类名：javadoc -d docs/api com.example.myapp.Utils com.example.myapp.model.User
四、验证与定制输出效果
生成完成后，打开 docs/api/index.html 即可浏览。常见问题及优化方式：
- 页面样式老旧？可添加
-stylesheetfile mystyle.css替换默认 CSS - 想支持搜索？JDK 11+ 默认启用；旧版本需加
-enablejmx无效，应升级 JDK 或用第三方插件 - 忽略测试代码？确保
-sourcepath不包含src/test/java - 生成离线可用的文档？默认就是离线 HTML，无需联网；如需压缩，可打包整个
docs/api目录 - 集成进构建流程？Maven 用户推荐使用
maven-javadoc-plugin，Gradle 用户配置javadoctask 即可
不复杂但容易忽略。
