php类注释必须使用标准phpdoc格式（/* /），正确标注@param、@return、@property、@method等标签，否则影响ide补全、静态分析和文档生成。
PHP 类注释不是可有可无的装饰，而是 IDE 补全、PHPStan/ Psalm 静态分析、生成文档（如 phpDocumentor）的前提。没写对 @param 或漏掉 @return，phpstan 就可能报错，PhpStorm 也识别不出返回类型。
类声明上方必须用 PHPDoc 块注释
不能用单行 // 或多行 /* */ 替代。只有以 /** 开头、每行以 * 对齐、以 */ 结尾的块，才会被解析为 PHPDoc。
- 错误写法：
/* 这是普通注释，不会被解析 */<br>class UserService {} - 正确写法：
/** <br> * 用户服务类，负责用户注册、登录和信息更新<br> */<br>class UserService {} -
@package和@author不强制，但团队协作中建议统一加@package（如@package App\Services），方便后续生成文档结构
@property 和 @method 必须写在类级 PHPDoc 中
这两个标签只在类声明正上方的 PHPDoc 块里生效，用于描述“魔术属性”或“动态方法”，比如 Laravel 的 Eloquent 模型或使用 __get/__call 的类。
-
@property告诉 IDE 和静态分析器：这个类虽无真实属性，但能读写$user->name/** <br> * @property string $name<br> * @property int $age<br> */<br>class User { ... } -
@method用于声明动态方法签名，否则调用$user->scopeActive()->get()时 IDE 会标红/** <br> * @method static User query()<br> * @method User active()<br> */<br>class User extends Model {} - 注意：这些标签不改变运行时行为，只是“告诉工具该这么理解”，写错类型（如把
@property int $id写成@property string $id）会导致 IDE 提示错误或静态分析误报
构造函数参数必须用 @param 显式标注
PHP 8+ 支持构造函数属性提升（public function __construct(public string $name)），但即使如此，仍需在类级 PHPDoc 中用 @param 描述每个参数——因为 PHPDoc 是给开发者和工具看的，不是给 PHP 解析器看的。
立即学习“PHP免费学习笔记（深入）”；
- 哪怕用了属性提升，也要补全：
/** <br> * @param string $name 用户姓名<br> * @param int $level 权限等级，默认 1<br> */<br>class User {<br> public function __construct(<br> public string $name,<br> public int $level = 1<br> ) {}<br>} - 如果参数是联合类型（如
string|null），@param必须写全：@param string|null $email，不能简写为@param string $email - PHP 8.0+ 的
mixed类型要显式写@param mixed $data，否则部分工具（如 PHPStan level 6+）会警告“缺少类型信息”
最常被忽略的是：类注释里的 @return 是留给静态方法的，不是给类本身用的；而 @var 只能用于变量赋值行上方，不能放在类 PHPDoc 里。混淆这些位置，注释就彻底失效了。
