idea生成javadoc乱码的关键在于源文件、读取工具、输出文档三端编码必须统一为utf-8：需在file encodings中设global/project/properties编码为utf-8，生成时填-encoding utf-8 -charset utf-8 -docencoding utf-8，并确认源文件右下角显示utf-8而非gbk或auto-detect。
IDEA里生成Javadoc文档总乱码？关键就三处编码要对齐
不是参数没加全，而是源码、读取、输出三端的编码不一致。只要有一处是GBK或默认系统编码，中文注释就会变成方块或问号。
-
File → Settings → Editor → File Encodings里把Global Encoding、Project Encoding、Default encoding for properties files全设成UTF-8 - 生成时在
Other command line arguments填：-encoding UTF-8 -charset UTF-8 -docencoding UTF-8 - 确保源文件本身保存为UTF-8（右下角状态栏确认，不是“GBK”或“Auto-detect”）
漏掉任意一项，javadoc 工具就会用平台默认编码读源码，哪怕你加了 -encoding 也救不回来。
Tools → Generate JavaDoc 配置项里哪些必须填？
很多用户卡在弹窗里反复试错，其实只有三项真正影响结果是否可用：
-
Scope：选Module最稳妥。选Project容易因依赖缺失报class not found；选单个类适合调试，但无法跨类解析{@link}链接 -
Output directory：建议填docs（相对路径），避免绝对路径导致迁移后链接失效 -
Locale：填zh_CN，否则导航栏、索引页标题等固定文本仍是英文，和你的中文注释割裂
Window title 和 Bottom text 属于美化项，不填也能生成可浏览的文档。
自动生成的方法注释老是缺 @param 或 @return？检查模板上下文
IDEA 默认只对 public 方法生成完整标签，private/protected 方法或构造器可能跳过 @param。这不是 bug，是模板作用域限制。
- 触发方式必须是光标停在方法名上，按
Alt + Enter→ “Add Javadoc”，而不是随便敲/** - 进
Settings → Editor → Live Templates → Java → Javadoc，确认模板的Applicable context包含Method declaration和Constructor declaration - 如果用了自定义变量（如
$VERSION$），记得在Edit variables里给它设好默认值，否则生成时会留空
另外，Kotlin 方法不生成 @param 是设计如此，别误以为插件坏了。
生成的 HTML 打开全是空白页？先看控制台报错
IDEA 界面不显示错误详情，但后台 javadoc 进程失败时会在底部 Build 工具窗口里打印原始错误。常见原因：
-
error: package xxx does not exist：说明Scope选太大，当前模块没引入依赖包。改用Module或手动加-classpath参数 -
warning: no comment：不是错误，只是提醒该类/方法没写 Javadoc，不影响生成，但链接会断 -
index.html里搜索不到类名：检查输出目录是否真有index-files和allclasses-index.html，没有说明生成中途失败，得回看控制台
最隐蔽的坑是 JDK 版本——Java 17+ 默认禁用 sun.* 包，如果项目用了旧版 Doclet，得加 --add-exports java.base/sun.nio.ch=ALL-UNNAMED，但这属于高级定制范畴，普通项目避开即可。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
