PhpStorm 仅在光标位于 class 关键字正前方时才可一键生成类 PHPDoc 模板；模板默认不含 @author/@package，需手动配置 Includes → PHP Class Doc Comment；@inheritdoc 不自动添加，须显式写入模板；文件头注释与类注释模板独立。
PhpStorm 不会自动为已有类生成完整 PHPDoc 注释，但可以一键插入符合规范的类文档模板——前提是光标位置、类结构和模板配置都正确。
光标必须放在 class 关键字正前方
这是最常被忽略的触发条件。不是放在类名后、不是花括号里、也不是空行上，而是紧贴在 class 关键字左侧（例如 class User { 这一行最开头）。此时输入 /** 再按 Enter，才会激活 PHPDoc 模板；若光标停错位置，只会生成普通多行注释。
- 错误位置示例：
User {行、{行、类内部任意行 - 正确位置示例：
class User {这一行最左端，光标在c前面 - 接口（
interface）和 trait 同样适用该规则
类注释模板默认不带 @author 和 @package，需手动配置
PhpStorm 自带的类文档模板（路径：Settings → Editor → File and Code Templates → Includes → PHP Class Doc Comment）只含基础结构，不包含项目常用的 @author、@package 或 @since。这些必须手动编辑模板添加，否则每次生成都得手补。
- 在模板中加入
* @author $USER$和* @package $NAMESPACE$（注意变量名大小写敏感，$NAMESPACE$需要 PhpStorm 能解析当前命名空间） -
$DATE$会自动展开为当天日期，但仅生成时计算一次，不会动态更新 - 别用
$date$—— 小写变量名无效，留空或报错
继承类或实现接口时，@inheritdoc 不会自动加
即使子类重写了父类方法，PhpStorm 默认也不会在类级 PHPDoc 中插入 @inheritdoc。这个标签需显式写进模板，或在生成后手动添加，否则文档工具（如 phpDocumentor）无法正确继承父类描述。
立即学习“PHP免费学习笔记（深入）”；
- 若团队规范要求所有子类声明继承关系，直接在
PHP Class Doc Comment模板末尾加一行* @inheritdoc - 注意：
@inheritdoc是 PHPDoc 标准扩展，不是所有静态分析器都支持，但 phpDocumentor 和 Psalm 都识别 - 对抽象类或接口本身，不建议加
@inheritdoc，它只用于“实现/继承上下文”
新建文件时的类头注释 ≠ 类文档注释
很多人混淆了“文件头部注释”和“类 PHPDoc 注释”。前者（PHP File Header）在新建 .php 文件时自动插入，属于文件级元信息；后者（PHP Class Doc Comment）是针对 class 结构本身的语义化文档，两者模板独立、触发时机不同、用途也不同。
- 文件头注释改的是 Settings → Editor → File and Code Templates → Files →
PHP File - 类文档注释改的是 Includes →
PHP Class Doc Comment - 改错地方会导致：新建文件有作者信息但类上没注释，或类上有注释但文件头空白
真正容易卡住的地方不在快捷键，而在模板变量是否生效、光标是否压准了 class 的左边界、以及 @inheritdoc 这种非自动生成却影响文档连贯性的标签——它们不会报错，但会让生成的文档在下游工具里断层。
