Composer脚本不处理注释，需用php-cs-fixer补全docblock（如@param、@return），或用sed/PowerShell插入文件头注释；但无法智能生成语义准确的完整注释，须人工校验。
Composer 脚本本身不处理注释，得靠外部工具链
Composer 只是依赖管理器，scripts 字段本质是 shell 命令调度器。想批量规范 PHP 文件注释（比如统一添加 @author、@since 或补全缺失的 docblock），必须组合使用静态分析或代码生成工具，不能指望 composer.json 里写几行 JSON 就自动改注释。
推荐用 php-cs-fixer + 自定义规则补 docblock
php-cs-fixer 是最贴近需求的现成方案：它支持 phpdoc_add_missing_param_annotation、phpdoc_add_short_description 等规则，还能通过 phpdoc_to_comment 把空 docblock 补成标准格式。但注意：它默认不生成完整函数/类头部注释（如 @package、@license），需配合自定义配置。
- 先安装：
composer require --dev friendsofphp/php-cs-fixer - 在项目根目录建
.php-cs-fixer.php，启用基础 docblock 规则：
return (new PhpCsFixer\Config())
->setRules([
'phpdoc_add_missing_param_annotation' => true,
'phpdoc_add_short_description' => true,
'phpdoc_no_empty_return' => true,
'phpdoc_no_useless_inheritdoc' => true,
])
->in(__DIR__.'/src');
- 加 Composer 脚本：
"fix-docs": "php-cs-fixer fix --config=.php-cs-fixer.php" - 运行：
composer fix-docs—— 它只会补全已有 docblock 中缺失的@param/@return，不会凭空加整个头部注释
要批量插入完整文件头注释？得用 sed / awk 或专用脚本
如果目标是给所有 .php 文件顶部插入统一版权/作者信息（例如 GPL 声明），php-cs-fixer 不适用。这时候更可靠的是轻量级文本处理：
- Linux/macOS 下直接用
sed批量追加（注意备份）：find src -name "*.php" -exec sed -i.bak '1s/^/\/\*\*\n \* @package MyPackage\n \* @author Me\n \* @license MIT\n \*\/\n/' {} \; - Windows 用户可用 PowerShell 替代：
Get-ChildItem -Path src -Recurse -Filter "*.php" | ForEach-Object { $c = Get-Content $_.FullName; Set-Content $_.FullName ("/**`n * @package MyPackage`n * @author Me`n * @license MIT`n */`n" + $c) } - 务必先测试单个文件，
sed -i没有撤回机制；PowerShell 的Set-Content会覆盖原文件，建议先Copy-Item
别踩坑：注释自动化 ≠ 语义正确
自动补 @param 依赖函数签名反射，如果用了 mixed、array 或 PHP 8.0+ 的联合类型（如 string|int），php-cs-fixer 可能漏判或写错格式；更麻烦的是动态调用（call_user_func）、魔术方法（__get）——这些它根本识别不了。
- 运行前先
git status确认没未提交变更，避免污染工作区 - 补完注释后必须人工抽检，重点看
@param类型是否与实际参数一致 - CI 流程中不要把注释修复设为强制检查项，容易因类型推断不准导致构建失败
真正难的不是加注释，而是让注释和代码行为保持同步。工具只能帮你省掉机械劳动，没法替代人盯住逻辑变化。
