windows/linux 默认按 / + 回车，macos 按 / + enter 可生成 javadoc 注释，需光标位于方法/字段/类声明行任意位置（含行尾），且须启用 settings → editor → general → smart keys 中“add javadoc stub”选项。
IDEA 里按什么快捷键能生成 JavaDoc 注释
Windows/Linux 默认是 /** + 回车，macOS 是 /** + Enter；光标必须紧贴在方法或字段声明行的最左侧（或任意位置但需在该行），否则会变成普通多行注释。
常见错误：先敲了 /** 再移动光标到行首，结果触发的是「普通注释包裹」而非 JavaDoc 模板；或者光标停在方法体内部，生成出来是空的 /** */。
- 确保光标位于方法签名、字段定义或类声明的同一行（哪怕在行尾也行）
- 输入
/**后立刻按回车——IDEA 会自动识别上下文并补全参数、返回值、异常等占位符 - 如果没反应，检查 Settings → Editor → General → Smart Keys → “Add JavaDoc stub on typing /** + Enter” 是否已勾选
生成的 JavaDoc 模板里哪些字段是自动填充的
IDEA 能根据方法签名自动填入 @param、@return、@throws，但仅限于基础类型和常见 JDK 类（如 String、List、IOException）。自定义类名、泛型细节、Lambda 参数等不会自动推导。
例如：public <t> List<t> filter(Predicate<t> p)</t></t></t> 会生成 @param p 和 @return，但 T 不会出现在描述中；@throws 只对显式声明的异常生效，不会扫描方法体。
-
@param名称和类型来自形参列表，但描述为空，需手动补全语义（比如“非 null 的过滤条件”） -
@return类型取返回值声明，但不带泛型具体参数（如只写List，不写List<string></string>） - 重载方法间若参数名相同，IDEA 不会自动区分描述，容易粘贴错
为什么有些方法生成不了 JavaDoc 模板
最常见原因是方法签名不符合 IDEA 的解析规则：构造函数若含 this(...) 调用、lambda 表达式作为参数、使用了未导入的类型别名（如 Lombok 的 @NonNull 注解干扰解析），都会导致模板生成失败。
另一个隐蔽原因是项目 SDK 配置异常：如果模块的 Language Level 低于 5，或 Project SDK 未正确指向 JDK（比如指向了 JRE），IDEA 会禁用 JavaDoc 智能补全。
- 检查 File → Project Structure → Modules → Sources → Language level ≥ 5
- 确认 Project SDK 指向的是完整 JDK（路径含
jdk-或Contents/Home），不是jre/ - 临时移除 Lombok 注解或
@NonNull等静态检查注解再试一次，确认是否为插件冲突
批量为已有方法添加 JavaDoc 的操作方式
不能靠快捷键逐个敲——要用 Code → Generate… → JavaDoc（Alt+Insert → J），但前提是方法已带有可识别的签名结构。它会跳过已有 JavaDoc 的方法，只处理空白处。
注意：这个功能对 private 方法默认不生成 @param（除非开启 Settings → Editor → General → Auto Import → “Optimize imports on the fly” 并勾选 “Add unambiguous imports”），且不会为 getter/setter 自动加 @return 描述。
- 选中目标方法、字段或类（支持多选），再按
Alt+Insert→JavaDoc - 生成后记得检查
@return是否漏掉——尤其对布尔型 getter（如isRunning()） - 若批量生成后大量
@param描述为空，建议用Ctrl+Shift+R替换\*\s+@param\s+(\w+)\s*→@param $1 TODO 描述快速打标
IDEA 的 JavaDoc 生成能力依赖于语法解析精度，遇到泛型嵌套、高阶函数或 Kotlin 互调场景时，字段推导容易出错；真正要保证文档可用，还是得人工核对参数含义和边界条件。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
