TP5自定义函数注释须写在common.php中并严格使用PHPDoc格式：顶格/**开头、紧贴函数、完整@param/@return/@throws，返回类型必须为\think\Response等实际对象类型，不可写array或遗漏。
TP5自定义函数注释要加在 common.php 里，且必须用 PHPDoc 格式
TP5 的 common.php 是全局函数文件，但框架本身不解析或校验其中的注释——注释只对 IDE、静态分析工具（如 PHPStan）、以及后续可能接入的文档生成器（如 apidoc）起作用。所以你写不写、怎么写，不影响运行，但影响协作和可维护性。
关键点是：必须用标准 PHPDoc 块注释（/** */），不能用单行 // 或多行 /* */，否则 PHPStorm、VS Code 的参数提示、跳转、类型推导基本失效。
-
/**必须顶格，紧贴函数声明上方，中间不能空行 - 每个
@param要写清类型和变量名，比如@param string $name，别写@param $name（类型丢失） -
@return后必须跟类型，void / array / int / \think\Response 等，不能留空 - 如果函数可能抛出异常，加上
@throws \Exception（尤其封装了数据库操作或 HTTP 请求时）
示例（放在 application/common.php 中）：
/**
* 统一 API 响应输出函数
* @param int $status 业务状态码，1 表示成功
* @param string $message 提示信息
* @param array $data 返回的数据体，可为空数组
* @param int $httpCode HTTP 状态码，默认 200
* @return \think\Response
* @throws \think\Exception
*/
function show($status, $message, $data = [], $httpCode = 200)
{
$data = ['status' => $status, 'message' => $message, 'data' => $data];
return json($data, $httpCode);
}
show() 这类函数的注释里，@return 类型必须写 \think\Response
很多人写成 @return array 或漏掉，结果在控制器里调用 return show(...) 时，IDE 会误判返回值类型，导致后续链式调用（比如想加 header）没提示，甚至类型检查报错。
原因很直接：json() 是 TP5 的助手函数，它内部返回的是 \think\Response 实例，不是原始数组。框架靠这个对象完成 Content-Type 设置、状态码发送、异常拦截等动作。
- 写
@return array→ IDE 认为你返回的是数组，->header()这类方法就没了提示 - 不写
@return→ PHPStan 直接报 “Missing return type” 错误 - 写
@return \think\Response→ 所有响应链路方法（header()、withCookie()、contentType()）都能被识别
顺带提醒：\think\Response 在 TP5.1+ 中路径没变，但如果你项目是 TP5.0，类名是 \think\response\Json，注释里就得对应写清楚。
注释里别硬编码路径或版本号，用相对命名空间
你在 common.php 里写的函数，很可能被模型、事件、命令行脚本等多处调用。如果注释里出现类似 @see application/api/controller/Test.php 这种绝对路径，一旦目录结构调整（比如从 api 拆成 v1、v2），所有注释都得手动改，且 IDE 不会帮你定位。
更稳妥的做法是用逻辑引用：
- 用
@see show()指向同文件内其他函数 - 用
@see \app\common\lib\exception\ApiHandleException指向具体类（注意反斜杠开头） - 需要说明使用场景时，写“常用于 API 控制器的统一输出”，而不是“见 Test.php 第 12 行”
另外，@deprecated 标记比删函数更实用。比如旧版 apiReturn() 已被 show() 替代，就在原函数注释头加一行：@deprecated use show() instead，调用时 IDE 会划删除线并提示替代方案。
别依赖 DocBlockr 自动补全来写函数注释
Sublime 的 DocBlockr 插件对类方法、控制器 action 注释支持较好，但它识别不了 common.php 里的自由函数——因为没上下文（没 class、没 namespace、没 visibility）。你敲 /** 回车，它大概率生成空模板或错误参数占位符（比如把 $data = [] 解析成 @param [type] $data = []）。
所以这类函数注释，老老实实手写，或用 IDE 内置模板（PHPStorm 输入 /** + 回车自动展开，VS Code 安装 PHP DocBlocker 插件后也支持）。重点检查三处：
- 参数个数是否和函数签名一致（特别是默认值参数要不要写
@param） -
@return类型是否与实际返回对象匹配（再次强调：不是json()的输入数组，而是它的返回值） - 有没有漏掉可能抛出的异常类型（比如
show()本身不 throw，但如果你封装了Db::transaction()，就要加@throws \think\db\exception\DataNotFoundException）
最易忽略的一点：TP5 的 common.php 是被所有请求共享加载的，里面函数的注释一旦写错类型，会影响整个项目的静态分析结果。宁可少写，也不要写错。
