PHP魔术方法注释必须写在声明上方且参数名须符合约定：__get/__set参数名分别为$name/$value，__invoke需标注callable类型，__destruct应说明副作用与执行不确定性。
PHP魔术方法注释必须写在声明上方，不能写在函数体内
PHP的魔术方法（如 __construct、__get、__toString）本身不支持返回类型声明（PHP 8.0+ 也不允许对它们加 void 或其他返回类型），所以文档注释（PHPDoc）是唯一能明确表达意图和参数含义的方式。如果把注释写在方法体内部，PHPDoc 解析器（比如 PHPStan、IDE）会完全忽略它。
- ✅ 正确位置：紧贴
function关键字前一行，且中间无空行 - ❌ 错误写法：
public function __toString() { /** @return string */ // IDE 看不见，静态分析不识别 return (string) $this->id; } - PHPDoc 中建议包含
@param、@return、@throws（如有异常逻辑）
__get 和 __set 的参数名必须写成 $name，否则 PHPDoc 失效
虽然 PHP 允许你把 __get 的参数起名叫 $key 或 $prop，但主流工具链（PhpStorm、PHPStan、Psalm）都依赖「约定参数名」来推断魔术行为。一旦改名，IDE 就无法正确补全属性访问、也无法识别动态属性的类型。
- ✅ 推荐写法：
/** * @param string $name 属性名（区分大小写） * @return mixed */ public function __get(string $name)
- ❌ 危险写法：
public function __get(string $prop) { ... }—— 此时$obj->foo在 IDE 中不会触发__get的类型提示 -
__set同理，第二个参数必须叫$value，否则类型推导断裂
__invoke 注释要标注 callable 类型，避免与普通方法混淆
__invoke 让对象可被当作函数调用，但它本质上仍是方法。如果不加明确注释，静态分析可能误判为“未使用的方法”，或在类型检查中丢失 callable 上下文。
- 必须标注
@return和输入参数，例如：/** * @param int $x * @param string $y * @return array */ public function __invoke(int $x, string $y): array
- 若该类常用于回调（如事件处理器），建议额外加
@implements \Closure或@psalm-callable（Psalm 场景） - 注意：PHP 8.0+ 支持
__invoke(): void，但 PHPDoc 仍应写@return void以兼容旧工具
__destruct 不需要 @return，但必须注明副作用和资源释放逻辑
__destruct 没有返回值，写 @return void 是冗余的；更重要的是，它执行时机不确定（可能在脚本结束前任意时刻），容易引发资源竞争或已销毁对象访问。注释里得把“做了什么”和“不能做什么”说清。
立即学习“PHP免费学习笔记（深入）”；
- ✅ 实用注释示例：
/** * 清理临时文件并关闭数据库连接。 * 注意：不保证在所有异常退出路径中都被调用； * 若需确定性释放，请显式调用 close()。 */ public function __destruct()
- 不要在
__destruct中 throw 异常 —— PHP 会静默吞掉，且可能中断垃圾回收 - 避免在其中调用
$this->otherMethod()，因为其他属性可能已被析构
实际项目里，最常被忽略的是 get/set 的参数命名约束和 __destruct 的执行不确定性——这两点不靠注释说清楚，后期 debug 成本远高于写几行说明。
