PHPDoc 是 PHP 官方推荐的文档注释标准，需以 /** 开头、*/ 结束，正确使用 @param、@return 等标签，类型标注须具体真实（如 array<int, string>），并随代码同步更新，避免过时或冗余描述。
PHPDoc 是 PHP 中广泛使用的文档注释标准，它不仅帮助开发者理解代码逻辑，还被 IDE、静态分析工具（如 PHPStan、Psalm）和文档生成器（如 phpDocumentor）识别和利用。写好 PHPDoc 的关键在于准确、简洁、符合规范，并与实际代码保持一致。
基本结构：以 /** 开头，每行以 * 对齐
PHPDoc 注释必须以 /** 开始，以 */ 结束，中间每行以 * 开头并保持缩进对齐。不能使用 /* ... */ 或 // 替代。
示例：
/**
* 计算两个整数的和
*
* @param int $a 左操作数
* @param int $b 右操作数
* @return int 两数之和
*/
function add(int $a, int $b): int
{
return $a + $b;
}
核心标签（Tags）要准确使用
常用 PHPDoc 标签有 @param、@return、@throws、@var、@see 等。每个标签后需紧跟类型、变量名（如适用）和说明，类型必须与 PHP 类型声明或运行时行为一致。
立即学习“PHP免费学习笔记（深入）”；
-
@param后跟 类型、变量名（带$）、说明，多个参数分行写 -
@return后跟类型和简要说明；若无返回值，写void -
@throws后跟异常类名和触发条件，如@throws InvalidArgumentException 当输入为负数时 -
@var用于变量或属性注释，格式为@var Type $name 描述
类型标注需真实、具体、可验证
优先使用 PHP 原生类型（string、int、bool、array、callable），支持联合类型（string|int）、泛型语法（array<string, User>）、nullable（?string 或 string|null），避免模糊表述如 mixed 或 object，除非确实无法限定。
注意：array 应尽量细化，例如：
- ✅
@param array<int, string> $names - ✅
@param list<User> $users（PHP 8.1+，表示数字索引数组） - ❌
@param array $data（过于宽泛，失去提示价值）
保持注释与代码同步，不写“废话”
注释应补充代码未言明的信息，而非复述代码。避免类似“设置用户名”“返回结果”这类无信息量描述。
- ❌
@param string $name 用户名（如果参数名已是$username，且方法叫setUsername()，这句多余） - ✅
@param string $username 必须为非空 ASCII 字符串，长度 3–20 位（补充约束） - ✅
@return ?Token 若认证失败返回 null（说明边界行为）
当函数逻辑变更时，务必同步更新 PHPDoc —— 过时的注释比没有更危险。
