Java文档注释不生成Javadoc的根本原因是项目未被IDEA正确识别为Java模块，需确保pom.xml或build.gradle已导入、源码路径标记为Sources Root，并在Project Structure中配置正确的JDK和模块SDK；生成时须手动指定含javadoc.exe的JDK路径，添加UTF-8编码参数，可见性选Package才能包含package-private类，而生产环境推荐使用Maven/Gradle命令行生成以保障稳定性和定制化能力。
Java文档注释不生成Javadoc？先确认IDEA是否识别为Java项目
IDEA不会自动为任意文件夹生成Javadoc，哪怕你写了@param和@return。核心前提是：项目必须被正确识别为Java模块（即包含pom.xml或build.gradle，且已成功导入），且源码路径标记为Sources（右键目录 → Mark Directory as → Sources Root）。
常见错误现象：Generate JavaDoc菜单灰掉、点击后弹出“no JDK specified”或“no source files found”。这时不是插件问题，而是项目结构没对。
- 检查
Project Structure → Modules里是否有Java模块，Sources路径是否指向src/main/java - 若用Maven，确保
pom.xml已右键 →Add as Maven Project，而非单纯打开文件夹 - 如果用了多模块，需在
Project Structure → Project Settings → SDKs中为每个模块指定JDK，不能只配Project SDK
生成Javadoc时提示“javadoc.exe not found”或编码乱码
这是JDK配置和命令行参数没对齐的典型表现。IDEA调用的是JDK自带的javadoc工具，不是IDE内置逻辑，所以路径、字符集、doclet都得手动对齐。
关键点在于：IDEA的Javadoc生成器默认复用项目JDK，但如果你装了多个JDK（比如JDK 8 + JDK 17），它可能选错——尤其当你只在Project SDK设了JDK 17，却在Module SDK里漏配，javadoc就找不到可执行文件。
立即学习“Java免费学习笔记（深入）”；
- 进
Tools → Generate JavaDoc → Output directory前，务必点开Configure JDK按钮，确认显示的是含bin/javadoc.exe（Windows）或bin/javadoc（macOS/Linux）的JDK路径 - 中文注释乱码？在
Other command line arguments里加：-encoding UTF-8 -docencoding UTF-8 -charset UTF-8 - 如果用了自定义
doclet（如standard-doclet以外的），要显式填入-doclet和-docletpath，否则会报class not found
为什么public类里的注释生成了，package-private类却没出现？
Javadoc默认只处理public和protected成员。IDEA的生成界面里有三个可见性选项：Public、Protected、Package，但很多人没注意——它控制的是“哪些类/成员会被扫描”，不是“生成后是否可见”。
也就是说，如果你选了Public，那连package-private类本身都不会被读取，更别说其内部注释。而Package选项才真正包含包内所有类（包括无修饰符类），但生成结果里仍按Javadoc规范隐藏非public成员细节（仅保留类名和brief description）。
- 想让包内所有类都出现在HTML索引页？必须选
Package，而不是依赖“默认值” - 如果类上有
@hidden或{@hide}，即使选Package也会跳过——这是Javadoc原生行为，IDEA不干预 - 注意：
Private选项在IDEA中实际不可用（会报错），别试
用Maven或Gradle生成更可靠？什么时候该切到命令行
IDEA的图形化Javadoc生成适合快速预览，但一旦涉及定制化（比如集成到CI、生成多语言文档、过滤特定包），它就力不从心。Maven的maven-javadoc-plugin和Gradle的javadoc任务才是生产环境标准做法。
一个容易被忽略的细节：IDEA生成时默认不校验@param是否与方法参数名一致，而Maven插件开启<failonerror>true</failonerror>后，遇到参数名拼错（比如@param userId但方法签名是String uid）会直接构建失败。
- Maven示例：在
pom.xml里加<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-javadoc-plugin</artifactid><version>3.6.0</version><configuration><sourcefileexcludes>**/internal/**</sourcefileexcludes></configuration></plugin> - Gradle示例：
javadoc { options.encoding = "UTF-8"; options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED } - IDEA里右键运行
mvn javadoc:javadoc比用GUI更稳定——因为复用项目pom配置，不依赖IDE缓存
真正复杂的地方在于跨模块依赖的类路径：IDEA GUI生成时自动补全依赖jar的源码路径（如果有），而命令行需要显式配置-link或<links></links>指向其他模块的Javadoc URL。这点没人提醒，但一出错就是“unknown tag @link”或者链接404。
