PHP函数注释必须遵循PHPDoc标准，以/*开头、/结尾，按@param→@return→@throws→@see顺序书写，类型需与运行时一致，参数名须与函数签名完全相同。
PHP 函数注释不是可有可无的装饰，而是 IDE 自动补全、PHPStan/PHP_CodeSniffer 检查、以及团队协作的前提。没写对 @param 或漏掉 @return，VS Code 就可能报 Undefined type，PHPStan 也会直接标红。
用 PHPDoc 标准写函数头部注释
PHP 官方不强制注释格式，但所有主流工具（PhpStorm、PHPStan、Psalm、phpDocumentor）都只认 PHPDoc 标准。必须以 /** 开始，每行以 * 对齐，结尾为 */；不能用 // 或 /* */ 替代。
关键标签必须按固定顺序出现：@param → @return → @throws → @see。顺序错乱会导致 PHPStan 解析失败。
-
@param类型必须与实际参数类型一致，支持联合类型如string|int（PHP 8.0+），但旧版工具可能不识别，建议用mixed+ 文字说明 -
@return不能省略，即使返回void也要显式写@return void - 多个同名标签（如多个
@param）必须一一对应函数参数顺序，错位会导致类型推断完全失效
/**
* 根据用户 ID 获取格式化昵称，空则返回默认值
*
* @param int $userId 用户唯一标识
* @param string|null $fallback 备用文本，为 null 时返回 '游客'
* @return string 格式化后的昵称（如「用户#123」）
* @throws InvalidArgumentException 当 $userId 小于 1 时抛出
*/
function formatUsername(int $userId, ?string $fallback = null): string
{
if ($userId < 1) {
throw new InvalidArgumentException('User ID must be positive');
}
return '用户#' . $userId;
}@param 类型写法要匹配运行时行为
PHP 是动态语言，但 PHPDoc 类型是静态分析的唯一依据。写错类型等于主动关闭类型检查。
立即学习“PHP免费学习笔记（深入）”；
- 数组类型统一用
array或更精确的string[]（PHP 7.4+）、array（PHP 8.1+），避免混用array|string这种模糊写法 - 对象类型必须写完整类名，如
User或\App\Models\User；相对命名空间不被识别 - 可为空必须显式标注：用
?string（PHP 7.1+）或string|null，二者等价，但前者更推荐 - 回调类型写
callable，不要写function或Closure—— 后者只是 callable 的一种实现
IDE 和静态分析工具依赖注释结构
PhpStorm 的参数提示、自动补全、重构重命名，全部依赖 PHPDoc 中的 @param 名称是否与函数签名一致。如果注释里写 @param int $uid，但函数定义是 function foo(int $userId)，IDE 就无法关联提示。
- 参数名必须完全一致，包括大小写和下划线风格（
$user_id≠$userId） - PHPStan 默认只扫描
/**开头的块注释，/*或//注释中的 PHPDoc 不解析 - 使用
@deprecated时，必须跟上替代方案，例如@deprecated use formatUsername() instead，否则 PHPStan 不会警告调用方 - 如果函数有默认参数，
@param仍需完整列出，不能省略带默认值的参数
最常被忽略的是：注释里的类型和 PHP 运行时实际返回值不一致。比如函数内部可能返回 false 表示失败，但 @return 只写了 string，PHPStan 就会误报类型错误 —— 此时应写成 @return string|false 并在文档中说明 false 的含义。
