phpstorm 自动生成 @param 和 @return 注释需手动触发：在函数定义上方输入 /** 后按 enter，且函数须有明确参数和可推断返回类型；@author 和 @date 需自定义 live template；@param 显示 mixed 表明类型推断失败；批量生成用 alt+insert（windows/linux）或 cmd+n（macos）。
PhpStorm 自动生成 @param 和 @return 注释的触发条件
PhpStorm 不会自动补全 PHPDoc，必须手动触发。最常用方式是输入 /** 后按 Enter（不是 Tab），光标在函数定义上方时才会生成带参数和返回值的完整注释模板。
- 函数必须有明确的参数列表（不能是
...$args或纯反射调用） - 返回类型需可推断：要么有
: void/: string等 PHP 7.1+ 类型声明，要么有@return已存在且 PhpStorm 能识别上下文 - 如果函数体为空或只含
return;，@return void会被生成；若含return $x;且$x类型明确，会尝试推断
自定义 PHPDoc 模板中 @author 和 @date 的写法
默认模板不包含 @author 或动态日期，需手动编辑 Live Template。
- 进入
Settings > Editor > Live Templates > PHP - 选中
phpdoc模板，点击右侧Edit variables - 为
USER变量设默认值（如yourname），为DATE设表达式date("Y-m-d") - 在模板正文里插入
* @author $USER$和* @date $DATE$
注意：date() 表达式只在生成时计算一次，不会实时更新。
为什么 @param 类型总是变成 mixed？
这是 PhpStorm 类型推断失败的典型表现，常见于以下情况：
立即学习“PHP免费学习笔记（深入）”；
- 参数未赋类型声明，且函数体内未出现对该变量的明确类型操作（例如没调用
$foo->method()或is_string($foo)） - 参数来自超全局数组（如
$_GET['id']），PhpStorm 默认不信任其结构 - 使用了动态变量名（
$$var）或复杂数组解构（[$a, $b] = $arr;）
解决办法：显式添加 PHP 8+ 参数类型（function foo(string $name): int），或在注释中手动写 @param string $name —— 后者会被 PhpStorm 识别并用于后续代码检查。
批量为现有函数添加 PHPDoc 的快捷方式
不用一个个手敲，用 Code > Generate > PHPDoc Comment（快捷键 Alt+Insert on Windows/Linux, Cmd+N on macOS）。
- 光标放在函数名上，或选中多个函数（支持多行、多文件 Ctrl+Click 选择）
- 生成结果依赖当前函数签名：有返回类型声明就写
@return，有参数类型就写@param，否则留空或填mixed - 如果项目已启用 Psalm/PHPStan，建议先运行静态分析，再生成注释 —— 避免把错误的
mixed当成“正确推断”保留下来
/**
* @param string $name
* @param int $age
* @return array
*/
function createUser(string $name, int $age): array { ... }真正麻烦的是那些历史遗留的无类型函数，它们的注释需要人工核对逻辑，不能全信自动生成的内容。
