Java API 文档生成全解：从 javadoc 原理到 Dokka 选型
Java API 文档生成全解：从 javadoc 原理到 Dokka 选型
JDK 与主流 Java 生态习惯用HTML API 文档交付公共接口说明。javadoc解析类型声明与/** ... */，生成可离线浏览的站点。下文按「为何要做 → 原理 → 怎么写 → 怎么跑 → 避坑 → 工程化 → 选型边界」顺序读即可；细节仍以你所装JDK 版本的官方说明为准。
目录
- 1. 为什么一定要会 javadoc
- 2. javadoc 到底在干什么
- 3. 注释怎么写才规范
- 4. 命令行：语法与选项详解
- 5. 中文乱码与包路径避坑
- 6. 常见问题速查
- 7. Maven / Gradle 怎么做
- 8. Dokka / OpenAPI 怎么选
- 9. javadoc 的局限：什么时候不该只靠它
- 10. 延伸阅读线索与免责声明
1. 为什么一定要会 javadoc
| 价值 | 说明 |
|---|---|
| 协作 | public/protected 契约有一致文字，减少口口相传。 |
| 维护 | 注释与签名同框，重构与 Code Review 可对齐。 |
| 交付 | 开源库、SDK、内部平台常以 API 站作为可检索契约。 |
2. javadoc 到底在干什么
它不是「把注释复制进 HTML」，而是声明解析 → 文档模型 → 注释绑定 → HTML 渲染。
| 阶段 | 要点 |
|---|---|
| 解析声明 | 关心签名级信息；源码若有解析级语法错误仍可能失败。 |
| 文档模型 | 要解析继承、实现与引用，才有「已知子类」「继承的方法」等页。 |
| 注释 | 只有/** ... */进入文档；/* */与//不算。 |
| 输出 | 生成多页 HTML 与样式表；重复运行会覆盖-d目录，勿把手工改 HTML 当长期方案。 |
要能解析引用类型，通常要配-classpath（类与 JAR）和-sourcepath（源码根），否则易出现cannot find symbol。
3. 注释怎么写才规范
示例类（可直接对照生成）
packagecom.example.demo;/** * 演示用户相关操作的示例服务（教学用）。 * * @author Demo * @version 1.0 * @since 11 */publicclassUserService{/** * 根据用户名解析演示用标识。 * * @param username 非空用户名 * @return 演示用整数标识 * @throws IllegalArgumentException 当 {@code username} 为空时 */publicintgetUserId(Stringusername){if(username==null||username.isEmpty()){thrownewIllegalArgumentException("username must not be blank");}returnusername.hashCode();}}生成后打开-d目录下的com/example/demo/UserService.html（路径随包名变化），新手可以对齐这几块预期：类说明与@author等元信息；方法签名；@param/@return/@throws段落；若类型有父类或实现的接口，页面还会有继承关系与「来自父类的方法」等导航（本示例类未演示继承时后者可能较简）。
常用标签速查
| 标签 | 用途 |
|---|---|
@param | 参数 |
@return | 返回值（void是否写依团队规范） |
@throws/@exception | 异常 |
@see | 参见其它类型或成员 |
@since | 引入版本 |
@deprecated | 过时说明，常配合{@link} |
@author/@version | 元信息 |
正文可用{@code ...}、<p>；复杂 HTML 注意可读性与静态页使用场景。
4. 命令行：语法与选项详解
与教材类读本一致，可把javadoc理解为：解析源文件中的声明与文档注释，依赖Java 编译器完成声明级分析（不关心方法体实现细节），在内存里建立类型与「使用」关系后再输出HTML；因此它会加载所引用到的类型，必须把引导类、扩展类与用户类置于可解析的classpath / sourcepath下。
4.1 命令语法与各参数位置
javadoc [命令选项...] [包名...] [源文件名...] [@files...]| 位置 | 含义 |
|---|---|
[包名] | 若干包名，空格分隔；不允许对包名使用通配符（如*）。 |
[源文件名] | 若干.java路径，空格分隔；可以带目录与通配符（如mypackage/*.java，依操作系统与 shell）。 |
[@files] | 一个或多个参数文件，每行可写包名或源文件路径，顺序任意，用来承载很长的列表。 |
4.2 文档包含范围（可见性）
| 选项 | 含义 |
|---|---|
-public | 仅文档化public的类型与成员。 |
-protected | 文档化protected与public（默认）。 |
-package | 文档化包可见、protected、public。 |
-private | 文档化全部（含 private）；体积大，对外发布前要权衡是否暴露内部细节。 |
-help | 打印命令行帮助后退出。 |
4.3 输出位置、概述页与 Doclet
| 选项 | 含义 |
|---|---|
-d目录 | 生成 HTML 的输出根目录（日常几乎必写；教材示意里常与index.html同级的javadoc文件夹对应）。 |
-overview文件 | 指定一个HTML 概述页来源，作为总体说明（如项目前端「概述」链接）。 |
-doclet类 | 使用自定义 doclet类生成非默认格式输出（插件式扩展）。 |
-docletpath路径 | doclet 类的查找路径（类路径）。 |
4.4 源码与类路径（解析引用所必需）
| 选项 | 含义 |
|---|---|
-sourcepath路径列表 | 在哪些目录下查找.java源文件（多路径用分隔符连接，风格随 OS）。 |
-classpath/-cp路径列表 | 在哪些位置查找已编译的用户类（.class、JAR），用于解析类型引用。 |
-bootclasspath路径列表 | 覆盖引导类（JDK 核心 API）的查找位置；一般仅在特殊 JDK/交叉场景使用，新版本 JDK 与模块路径并存时需对照文档。 |
-source版本 | 按指定Java 语言级别解析源码（与javac的源版本选项同类）；较新 JDK 上也可能见到--source/--release等写法，以本机javadoc --help为准。 |
-extdirs目录列表 | 覆盖扩展库安装目录（经典 JDK 布局下的扩展机制；实际项目更常见显式 JAR + classpath）。 |
4.5 包与子包范围
| 选项 | 含义 |
|---|---|
-subpackages包前缀列表 | 从给定包起递归装入子包并生成文档。 |
-exclude包列表 | 排除不需要文档化的包（与-subpackages等配合筛范围）。 |
4.6 本地化、编码与运行参数
| 选项 | 含义 |
|---|---|
-encoding名称 | 源文件编码（如UTF-8）；中文项目常必选。 |
-charset名称 | 生成的HTML 声明的字符集；与-encoding常成对使用以避免乱码（教材未单列此项，但实践必备）。 |
-locale名称 | 生成文案所用的语言环境（如en_US）；影响某些默认措辞。 |
-breakiterator | 用BreakIterator判定「第一句」摘要边界（注释首句摘要展示相关）。 |
-verbose | 输出 javadoc执行过程的较多日志。 |
-quiet | 抑制常规状态信息（仅保留错误/警告等，依版本而定）。 |
-J标志 | 把后续标志直接传给javadoc 所运行的 Java 虚拟机（如内存参数）；注意紧跟-J后无空格那种经典写法。 |
4.7 教材示例命令勘误
有的读本示例会出现笔误，例如把工具名写成javacdoc、把通配符写成*.jara。正确意图一般为：
javadoc mypackage/*.java-djavadoc含义：为mypackage下匹配的源文件生成文档，输出到当前目录下的javadoc文件夹；若用包名递归，更常见配合-sourcepath与-subpackages。
4.8 进阶与模块化（简记）
--module-path、--add-modules等选项在JPMS 模块化项目中常见；与本文教材列举的经典选项并存，完整列表以当前 JDK 的javadoc -help/ 官方 Tool Guide 为准。
IDE 小技巧：日常在类/方法上敲/**往往能快速生成模板；实验、考试、CI仍以命令行或构建插件参数为准，便于复现。
5. 中文乱码与包路径避坑
目录必须与package一致，否则包索引与链接易乱：
src/com/example/demo/UserService.java → package com.example.demo;中文源码务必同时指定读入与写出编码，例如：
javadoc-encodingUTF-8-charsetUTF-8\-sourcepathsrc-ddoc/javadoc-protected\com.example.demoWindows 多行可用^，PowerShell 可用反引号；Unix 系常用\。
站点入口：生成后打开doc/javadoc/index.html（或你的-d）。常见页面还有包摘要、各类型的详情页（类名.html）；JDK 版本不同，导航框架（是否 frameset 等）可能略有差异。
6. 常见问题速查
| 现象 | 常见原因 | 方向 |
|---|---|---|
| HTML 乱码 | 编码未配对 | -encoding与-charset齐设 |
cannot find symbol | 缺依赖 | -classpath/-sourcepath |
没有private | 默认-protected | 需要时加-private（对外发布慎用） |
| 包里缺类型 | 包名写错或未递归 | -subpackages或显式列包 |
7. Maven / Gradle 怎么做
| 场景 | 做法 |
|---|---|
| Maven | maven-javadoc-plugin，如mvn javadoc:javadoc；在pom.xml固定编码与附加 classpath。 |
| Gradle | tasks.withType(Javadoc) { options.encoding = "UTF-8" ... }；或与 Dokka 等插件并用。 |
CI 可把target/site/apidocs或自定义输出目录发布为静态站（脱敏与权限另议）。
8. Dokka / OpenAPI 怎么选
Java/Kotlin 源码级 API 文档
| 方案 | 何时想到它 |
|---|---|
| javadoc | Java 库默认答案。 |
| Dokka | Kotlin 为主或 Kotlin/Java 混编；可读 Javadoc 风格注释，输出含现代 HTML、Markdown 等。 |
| Doxygen | 多语言混栈、能接受配置成本时偶见。 |
| Doclava | 老 Android 文档路线之一；新项目一般不首选。 |
REST 契约（另一件事）
| 方案 | 说明 |
|---|---|
| OpenAPI（含 Swagger UI 等） | 描述 HTTP API，不替代Java 类型上的 javadoc/Dokka。 |
记忆：库/SDK 看 javadoc 或 Dokka；对外 HTTP 看 OpenAPI；可以同时都要。
9. javadoc 的局限：什么时候不该只靠它
| 不太适合单靠 javadoc | 更适合的载体 |
|---|---|
| 业务流程、需求背景、跨模块故事 | Wiki、设计文档、ADR |
| 动态配置、规则表、运维手册 | 专用文档库或配置说明 |
| 「为什么这样设计」的长论述 | 架构文档 / 评审记录 |
| 很适合用 javadoc | 说明 |
|---|---|
| 对外稳定的 Java API | 方法契约、参数、异常、过时迁移 |
| 公共库 / 框架扩展点 | 与签名强绑定，读者按类型检索 |
边界想清楚，就不会出现「把所有业务文档塞进/** */」的反模式。
10. 延伸阅读线索与免责声明
| 检索线索 | 用途 |
|---|---|
JDKjavadoc手册 /man javadoc | 以当前 JDK 为准的选项与模块语法。 |
| Maven Javadoc Plugin、Gradle Javadoc、Dokka | 工程化与多模块路径。 |
免责声明：不同 JDK 大版本的 CLI 与默认 HTML 布局会变；本文不绑定某一版截图或 skin。
javadoc 适合把「能写在声明旁的契约」说清楚；流程与故事交给对的文档形态，反而更专业。