phpdoc 是 php 的标准文档注释规范，以 /* 开头、/ 结尾，紧贴被注释元素上方；常用 @param 和 @return 标签声明类型与含义，辅以 @throws、@var、@see、@deprecated 等标签提升可读性与工具支持。
PHPDoc 是 PHP 的标准文档注释规范，用于为类、方法、属性、函数等添加结构化说明，既方便 IDE 智能提示和类型检查，也支持通过工具（如 phpDocumentor）自动生成 API 文档。
基础格式：以 /** 开头，*/ 结尾
PHPDoc 注释必须用 /** ... */（双星号开头），不能用 /* ... */ 或 //。它紧贴在被注释元素的上方，中间不留空行。
- ✅ 正确：
/**
* 计算两个整数的和
*/
function add(int $a, int $b): int {
return $a + $b;
} - ❌ 错误：单星号、空行、位置错位都会导致解析失败或 IDE 不识别。
@param 和 @return 是最常用标签
它们明确声明参数类型、含义和返回值类型、含义，对类型安全和代码可读性至关重要。
-
@param 类型 $变量名 描述—— 类型支持原生类型（int、string）、类名（User）、联合类型（int|string）、可空（?array）、数组语法（int[]或array<string user></string>） -
@return 类型 描述—— 返回类型需与实际一致；若无返回值写@return void - 示例：
/**
* 根据邮箱查找用户
* @param string $email 用户邮箱地址
* @return User|null 找到则返回 User 对象，否则返回 null
*/
function findUserByEmail(string $email): ?User { ... }
其他高频实用标签
根据上下文选择补充，不强制全写，但关键信息建议覆盖。
-
@throws 异常类 描述—— 明确标出可能抛出的异常，比如@throws InvalidArgumentException -
@var 类型 $变量名—— 用于注释属性或变量（尤其在 PHP 7.4 之前缺乏属性类型时）
例如：/** @var string|null */ private $name; -
@see 关联元素—— 指向相关方法、类或外部资源，如@see self::validate() -
@deprecated—— 标记已弃用，可加版本号和替代方案，如@deprecated since v2.1, use newMethod() instead
风格与细节建议
保持简洁准确，避免冗余，兼顾机器可读与人工可读。
- 首行简明概括功能，不要以“该方法…”开头，直接说“创建订单并发送通知”
- 描述用中文即可，但类型、类名、方法名保持英文和原始大小写
- 多行描述时，每行缩进 1 个空格（非 Tab），保持对齐美观
- IDE（如 PhpStorm）支持自动补全 PHPDoc 模板，输入
/**后回车即可生成骨架，再填内容更高效
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
