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