PHP接口注释必须用@method显式声明方法签名，参数名、类型和返回值须与接口声明严格一致，继承时需重复父接口的@method并注明重载，禁止包含实现细节或非强制约束。
PHP 接口（interface）本身不包含实现，但注释必须清晰表达契约意图——不是“这段代码做什么”，而是“实现者必须保证什么”。严谨的接口注释核心在于：用 @method 描述可调用行为，用 @param/@return 约束签名，且所有类型必须与实际声明一致。
接口文档必须用 @method 显式声明每个方法
PHP 的 interface 无法在 docblock 中直接写 @param 或 @return 在接口定义处（因为 PHP 解析器不支持），所以必须用 @method 伪指令完整描述每个方法签名。否则 IDE 无法推导类型，静态分析工具（如 PHPStan、Psalm）也会忽略契约约束。
常见错误是只写自然语言描述，例如：
/** * 用户服务接口 * getProfile() 返回用户资料 */
这毫无机器可读性。正确写法是：
立即学习“PHP免费学习笔记（深入）”；
/** * 用户服务契约 * * @method array getProfile(int $userId) 获取指定用户的完整资料数组 * @method bool updateUser(int $userId, array $data) 更新用户信息，成功返回 true */
@method签名必须与实现类严格一致
@method不是自由发挥的说明，它会被 PHPStan/IDE 当作真实方法签名来校验。任何偏差都会导致误报或类型丢失：
- 参数名必须完全匹配（
$userId不能写成$id） - 类型必须与接口中
function getProfile(int $userId): array;声明一致（不能省略int或写成integer） - 返回类型必须精确（
array≠array|string，后者需显式写成联合类型） - 如果方法有可选参数，
@method必须带默认值（如string $format = 'json'）
接口继承时，子接口注释要覆盖父接口并补充新契约
当一个接口 extends 另一个接口，子接口的 docblock 必须重新声明所有继承来的方法（包括父接口里的 @method），否则工具会丢失父接口的契约信息。不能只写新增方法。
例如：
/**
* 基础存储接口
*
* @method mixed get(string $key)
* @method void set(string $key, mixed $value, int $ttl = 0)
*/
interface CacheInterface {}
/**
- 带前缀的缓存接口
- @method mixed get(string $key) 重载：自动添加命名空间前缀
- @method void set(string $key, mixed $value, int $ttl = 0) 重载：键名自动加前缀
- @method string getPrefix() 返回当前使用的前缀字符串
*/
interface PrefixedCacheInterface extends CacheInterface {}
注意：即使只是语义重载，也要重复声明父接口的
@method，并在描述中注明“重载”或“增强”，避免歧义。别把接口注释写成实现说明
接口注释里禁止出现以下内容：
- 具体实现路径（如
// 使用 RedisDriver） - 内部状态描述（如
// 内部维护一个连接池） - 性能提示（如
// O(1) 时间复杂度—— 这属于实现细节，接口不承诺性能） - 非强制约束（如
// 建议传入非空字符串—— 接口只规定类型和行为，不处理建议）
接口注释的唯一职责是：让实现者一眼看清「必须提供哪些方法」「每个方法接收什么」「必须返回什么」。多一个字，就多一分误解风险。
- 具体实现路径（如