Composer本身不生成文档，所有“自动生成”均由PHPDocumentor等外部工具完成；其自动化本质是通过composer.json的scripts封装调用命令，而非Composer自身能力。
Composer 本身不生成文档，所有“自动生成”的实际工作都由外部工具完成；你看到的自动化效果，本质是用 composer.json 的 scripts 把 PHPDoc 工具链封装成了可复用命令。
为什么 composer install 不会自动出文档
因为 Composer 只做三件事：解析 composer.json、下载包到 vendor/、生成自动加载映射。它不读 PHPDoc 注释，不扫描类结构，也不调用 phpdocumentor 或 doctum。常见错误是把 phpdocumentor/phpdocumentor 放进 require-dev 就以为万事大吉——其实只是装进了 vendor/bin/phpdoc，后续仍需显式运行。
-
post-install-cmd或post-autoload-dump钩子里直接写生成命令，会导致每次composer install都触发全量文档重建，CI 构建变慢、本地开发卡顿 - 想让文档真正“自动”，得靠 CI/CD（如 GitHub Actions）监听
src/变更后执行composer run docs，而非依赖 Composer 自身生命周期 -
composer dump-autoload不会触发任何文档逻辑，它只刷新类映射，和注释解析完全无关
怎么配 composer.json 的 scripts 才可靠
核心原则：脚本只负责调用，不嵌逻辑。所有路径、参数、模板都应外置，避免 JSON 字符串内转义和调试黑洞。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 用
"docs": "php vendor/bin/phpdoc --config=phpdoc.xml"，而不是"docs": "phpdocumentor -d src -t docs/api"—— 前者靠配置文件管理路径与排除规则，后者每次改目录都要改命令 - 如果项目含私有 SDK，且命名统一为
corp/*，在phpdoc.xml的<directory>里加vendor/corp/internal-sdk/src，别指望composer show输出能自动喂给文档工具 - 加
--force参数（如"docs": "php vendor/bin/phpdoc --config=phpdoc.xml --force"），否则缓存可能让你看不到刚写的@param string $id更新 - 不要在
scripts里写exec()或shell_exec()，PHP CLI 环境和 shell 终端行为不一致，容易在 CI 中静默失败
phpdoc.xml 里最容易填错的三个地方
90% 的生成失败或输出为空，都卡在这三项配置上。它们不是可选装饰，而是强制路径锚点。
-
<directory>src</directory>必须是相对于phpdoc.xml文件所在位置的路径，不是项目根目录；若phpdoc.xml在docs/下，就得写../src -
<exclude>src/Tests</exclude>要写全路径片段，不能只写Tests；漏掉这一行，phpdocumentor会尝试解析测试类里的$this->mock()，然后报 “Class not found” 警告并跳过整个命名空间 -
<version number="*"></version>设为*才能从composer.json的version字段自动取值；设成"1.2.0"就是硬编码，发版时必须手动同步改两处
真正难的不是跑通第一次生成，而是让文档持续准确：每次改 public function save(User $user): bool，就得同步更新 @param 和 @return；否则 phpdocumentor 输出的永远是过期接口。工具链再顺，也救不了没维护的注释。
