IntelliJ IDEA 自动生成 @param 和 @return 需光标置于方法声明正上方空行处并输入 /** 后回车；若未生效，需检查“Insert documentation comment stub”是否启用，并注意泛型、重载、record 等特殊场景下解析可能失败。
IntelliJ IDEA 自动生成 @param 和 @return 的触发条件
IDEA 不是“写完方法就自动补全 JavaDoc”，而是必须主动调用生成动作，且光标需停在方法签名正上方空行处。常见错误是写完方法体再按 /** + Enter，此时只会生成空模板，不会解析参数和返回值。
- 正确做法：把光标放在方法声明的上一行（比如
public String getName()上面那行），输入/**后回车 - 若已写好方法体，删掉已有注释，把光标挪到签名正上方再试一次
- 如果仍不生成
@param，检查是否启用了「Insert documentation comment stub」：设置路径为Settings > Editor > General > Smart Keys > Java > Insert documentation comment stub - 泛型方法、重载方法、Lambda 参数等场景下，IDEA 可能漏识别，需手动补全
自定义 JavaDoc 模板中 $param 和 $return 的实际行为
IDEA 的 Live Template 里写的 $param 并非简单占位符，它依赖于当前上下文的 AST 解析结果。不是所有变量名都能被正确映射，尤其当参数是 var 或使用了 record 构造函数时。
-
$param展开后是带换行的多行@param name desc，每行一个参数；$return只在返回类型非void时生效 - 模板中不要手动写
@param $param，直接写$param即可，IDEA 会自动加上标签和缩进 - 如果方法有多个同名参数（如重载导致 IDE 混淆），
$param可能只生成一个或顺序错乱，建议改用$PARAMETER_NAMES$+ 手动对齐 - record 的构造函数默认不触发
$param，需单独为record类型新建模板，用$FIELDS$替代
VS Code + Java Extension Pack 下无法生成标准 JavaDoc 的关键配置项
VS Code 默认不支持智能解析参数生成 @param，必须启用 java.configuration.updateBuildConfiguration 并确保项目加载为 Java 项目（而非普通文件夹）。
- 确认
settings.json中设置了"java.configuration.updateBuildConfiguration": "interactive" - 右键
pom.xml或build.gradle→ “Import project”，否则 Java 扩展无法读取依赖和源码结构 - 快捷键
Alt + Shift + J（Windows/Linux）或Option + Shift + J（macOS）仅在光标位于方法名上时有效，不在签名行无效 - 如果提示 “No Java project found”，说明语言服务器未激活，检查状态栏右下角是否有
Java标识，没有则重启 VS Code 并等待 Language Support for Java 启动完成
JavaDoc 模板里写 @since 和 @deprecated 的实际影响
这两个标签不会被 IDEA 或 javadoc 工具校验合法性，但会影响生成的 HTML 文档结构和 IDE 的代码提示行为。
立即学习“Java免费学习笔记（深入）”；
-
@since值必须是字符串，如"1.8"或"v2.1"，不能写成2.1（无引号会被忽略） -
@deprecated必须紧接在类/方法注释块开头，且后面要跟空格和说明文字，否则 IDE 不会标记删除线，javadoc 也不会归入 deprecated 列表 - 如果模板中固定写了
@deprecated，但实际方法没加@Deprecated注解，会导致文档与代码行为不一致，建议只在模板中留占位符@deprecated <reason></reason>，由人工判断是否填写 - 使用
@since后，IDEA 的「Find Usages」能过滤出指定版本后新增的 API，但前提是项目开启了java.completion.enabled
@Builder 方法这些场景，IDE 不会主动告诉你“我解析不了”，而是静默生成残缺内容。手动补全前，先确认光标位置、项目加载状态、以及模板变量是否匹配当前语言特性。 
