最可靠方式是Alt+Enter（macOS为Option+Enter）在函数定义正上方空白行触发“Add PHPDoc block”，可自动提取参数名、类型及返回值；/**+Enter因光标位置要求严苛而常失效。
PhpStorm 生成 PHPDoc 注释最可靠的方式不是靠 /** + Enter，而是用 Alt + Enter（macOS 是 Option + Enter）在函数定义上方触发意图操作——它不挑光标位置、能自动识别类型、还能跳过空 @return 行。
为什么 /** + Enter 经常失效
这个组合只在极少数位置生效：光标必须严格卡在 function 或 class 关键字正前方（比如 function getName 这一行，光标得在 f 左边），稍偏一点（类名后、花括号里、空行上）就只会插入普通块注释。很多人反复按却没反应，问题基本都出在这儿。
- 接口（
interface）、trait 同样适用该规则，但魔术方法如__invoke默认不被识别，需手动开启 Settings → Editor → Inspections → PHP → PHPDoc → “Treat __invoke as documented method” - 闭包（
$callback = function($x) {）完全不支持自动生成 - 类属性不能用此方式生成，得手写
/** @var string $name */
Alt + Enter 在函数上方才是主力操作
把光标放在函数声明正上方的空白行（哪怕前面有注释或空行也没关系），按 Alt + Enter → 选 “Add PHPDoc block”，就能生成带 @param、@return 的完整结构。它能准确提取 PHP 8+ 类型声明（如 function foo(string $name): int），也支持参数解构和返回值推断。
- 若函数无返回值（
void），默认模板可能仍生成空@return行——进 Settings → Editor → Live Templates → PHP →phpdoc模板，勾选Skip if the field is empty对应@return字段 - 异常（
@throws）不会自动识别，除非函数签名里显式写了throws Exception；想统一加，直接改模板 - 不依赖光标是否贴着关键字，容错率高，适合日常开发中快速补文档
批量补旧代码的 PHPDoc 怎么做
别一个个手点，用 Missing PHPDoc inspection 驱动灯泡提示更高效。先在 Settings → Editor → Inspections → PHP → Code Style Issues 中启用 “Missing PHPDoc comment”，设为 Warning 级别。之后 PhpStorm 会在所有未注释的方法/类上标黄波浪线，把光标停上去，按 Alt + Enter 就能一键补全。
立即学习“PHP免费学习笔记（深入）”；
- 支持多文件、多方法批量选中（Ctrl+Click 多个函数名），再按
Alt + Insert→ “PHPDoc Comment” 一次生成 - 生成结果严格依赖当前签名：有
: string就写@return string，没类型就留@param mixed $x或空着 - 模板里没
@author或@package？得手动改 Settings → Editor → File and Code Templates → Includes → PHP Function Doc Comment，加* @author $USER$和* @package $NAMESPACE$（注意大小写，$NAMESPACE$仅在命名空间可解析时才展开）
真正容易被忽略的是模板变量大小写敏感（$DATE$ 有效，$date$ 无效），以及 @inheritdoc 只应在子类/实现类中使用，抽象类和接口本身加了反而误导静态分析器。
