PHP参数注释仅用于IDE提示、静态分析和文档生成，必须用/* @param 类型 $参数名 /格式写在函数上方DocBlock中，类型与签名须严格一致。
PHP 中参数注释本身没有运行时作用，它只服务于 IDE 提示、静态分析（如 PHPStan、Psalm）和生成文档（如 phpDocumentor），@param 是唯一标准写法，必须写在函数/方法的 DocBlock 里，且紧贴函数声明上方。
参数注释必须写在 DocBlock 里，不能用单行//或#
PHP 解析器完全忽略 @param，只有工具读取 DocBlock（即 /** */ 块注释）里的标签。用 // @param string $name 不会被识别，IDE 不会提示类型，PHPStan 也不会校验。
- ✅ 正确位置：
/** @param string $name */紧挨着function或public function上方 - ❌ 错误写法：
// @param string $name或/* @param string $name */（非 DocBlock 格式） - ⚠️ 注意：DocBlock 必须是
/**开头（两个星号），不是/*
@param 的语法顺序和必填项
格式固定为：@param + 类型 + 参数名 + 可选描述。类型和参数名之间用空格分隔，参数名必须带 $ 符号，否则工具解析失败。
- 基础写法：
@param string $name 用户姓名 - 支持联合类型（PHP 8.0+）：
@param string|int $id - 支持数组结构化标注：
@param array{name: string, age: int} $user - 可为空需显式写
|null：@param string|null $email（不要只写string然后实际传null） - 无描述时也得留空格：
@param bool $debug（末尾空格不能省，否则部分工具截断）
常见踩坑：类型写错、漏写$、与实际签名不一致
注释类型和函数定义必须严格对应，否则 IDE 提示错乱、PHPStan 报告假阳性错误。尤其注意：
立即学习“PHP免费学习笔记（深入）”；
- 标量类型别名要统一：用
bool不用boolean，用int不用integer（虽然都认，但推荐短形式） - 对象类型写完整类名：
@param DateTimeInterface $date，不能只写@param DateTime（除非已 use） - 可变参数（
...$args）要标成数组：@param array$args - 如果参数有默认值
= null，注释里仍要写|null，不能省略
/**
* 创建用户
* @param string $name 用户姓名，不能为空
* @param int|null $age 年龄，可选
* @param array{role: string, active: bool} $meta 元数据结构
*/
function createUser(string $name, ?int $age = null, array $meta = []): array
{
return ['name' => $name];
}
最易被忽略的是「注释类型和实际类型提示（type declaration）同时存在时，两者必须兼容」——比如函数签名写了 string $name，注释就不能写 @param int $name，否则 PHPStan 会直接报错，不是警告。