<p>ThinkPHP本身不定义专属注释语法，仅使用标准PHP注释（//、/ /、/ /）；框架不解析普通注释，仅PHPDoc（/ /）可被IDE或Swagger等工具通过反射利用，但TP自身不读取执行。</p>
ThinkPHP 本身不定义专属注释语法，它用的就是标准 PHP 注释：//、/* */ 和 /** */。你写错的不是 ThinkPHP 规范，而是 PHP 基础注释规则或 PHPDoc 语义约定——这点必须先划清。
ThinkPHP 里哪些注释会被框架识别
ThinkPHP 不解析 // 或 /* */，也不靠它们做任何逻辑处理。唯一被框架间接“用到”的，是 PHPDoc（即以 /** 开头的文档注释），前提是配合反射（Reflection）或第三方工具（如 IDE、phpstan、Laravel IDE Helper）。比如你在控制器方法上写：
/**
* 用户列表接口
* @param int $page 页码
* @return array
*/
public function list($page = 1)
{这不会让 ThinkPHP 自动校验参数或生成路由，但 IDE 能跳转、phpstan 能检查类型、Swagger 插件能抽字段——这些能力依赖的是 PHPDoc 标准，不是 ThinkPHP 自研语法。
- ThinkPHP 的
Route::rule()、validate()等机制，靠的是配置数组或验证类，不是读取函数注释 - 模型字段注释（如
user_name的“用户昵称”）存在 MySQL 的information_schema.columns.column_comment，和 PHP 文件里的注释完全无关 - 模板里的
{// 这是模板单行注释}是 ThinkPHP 模板引擎自己的语法，只在模板文件中生效，不属于 PHP 语言层注释
PHPDoc 写错就等于没写：三个硬性条件
写了 /** 却没效果？大概率卡在这三处，和注释内容无关：
立即学习“PHP免费学习笔记（深入）”；
- 函数声明前**不能有空行**：
function foo() {}上面隔了一行，IDE 就断开关联 -
@param的变量名必须和函数签名**完全一致**，包括大小写（$UserId≠$userid） - 项目必须有
composer.json且已运行composer install——很多 IDE 依赖vendor/autoload.php加载类型信息
常见错误现象：PhpStorm 不提示参数、vscode 的 intelephense 报 Undefined variable $xxx、类型推导全成 mixed。
数据库字段注释和 PHP 注释是两套系统
很多人混淆“MySQL 字段 COMMENT”和“PHP 代码注释”。ThinkPHP 的 Db::getFields() 返回的数组里**没有 comment 字段**，因为那是 MySQL 元数据，不是 PHP 注释。要拿到字段中文描述，得手动查：
SELECT column_name, column_comment FROM information_schema.columns WHERE table_schema = 'your_db' AND table_name = 'user';
这里容易踩的坑：
- 线上数据库用户可能没权限查
information_schema，直接报错或返回空 - MySQL 版本低于 5.7，
column_comment可能为空或乱码 - 连接字符集没设对（比如配置里漏了
'charset' => 'utf8mb4'），中文注释显示为问号 - 阿里云 RDS 等云数据库会过滤
column_comment，这时只能靠建表 SQL 或人工维护映射表
模板注释不是 PHP 注释
ThinkPHP 模板引擎支持自己的注释语法，仅在 .html 或 .tpl 模板文件中生效，PHP 解析器完全不认：
- 单行：
{// 这行不会输出到页面} - 多行：
{<!-- 这段也不会输出 -->}或{/* 这样也行 */}
注意：这些写法如果误放进 PHP 控制器或模型里，会当成普通字符串或语法错误。模板注释和 PHP 注释不能混用，也不能互相替代。
真正容易被忽略的复杂点是：字段注释从数据库来、接口描述从 PHPDoc 来、模板文案从两者桥接而来——它们之间没有自动同步机制，靠人维系一致性。一旦建表时改了 COMMENT，不手动更新 PHPDoc 或模板映射，前端 label 就会和数据库语义脱节。
