Composer本身不生成API文档，所有“自动生成”均依赖phpdocumentor等外部工具，通过composer.json的scripts封装调用实现；需显式配置源码路径（如src）、排除无关目录，并确保PHPDoc注释完整规范。
Composer 本身不生成 API 文档，也永远不会支持——它不是代码分析器，不会读取 @param 或解析 public function save(): void 的返回类型。 所有“Composer 自动生成文档”的说法，本质是把 phpdocumentor、doctum 或 sami 这类工具通过 composer.json 的 scripts 封装起来，让人误以为是 Composer 在干活。
phpdocumentor v3 配置必须显式指定 src/，否则扫 vendor/ 报错
默认运行 phpdoc 会递归扫描整个项目目录，包括 vendor/、tests/、build/。结果不是生成慢，而是直接失败：Class "PHPUnit\Framework\TestCase" not found —— 因为 phpdocumentor 尝试解析测试类，但没加载 PHPUnit 的 autoloader。
-
<directory></directory>必须写成相对路径，比如src（不是./src或绝对路径） - 用
<exclude></exclude>排除测试和示例代码：src/Tests、src/Examples、src/Stubs - 不要依赖
psr-4映射自动推导源码位置；phpdocumentor 不读composer.json的 autoload 字段 - 缓存目录（
<cache></cache>）建议设为docs/cache，避免每次全量解析
想包含第三方包接口？手动加 vendor/ 中的 src 路径
phpdocumentor 默认跳过 vendor/，这是对的——你一般不需要把 Monolog 或 Guzzle 的全部内部方法塞进自己项目的文档里。但如果你真要暴露“本项目依赖了哪些公共接口”，就得主动加：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 在
phpdoc.xml的<fileset></fileset>里再加一个<directory>vendor/monolog/monolog/src</directory> - 路径必须精确到源码目录，不是
vendor/monolog/monolog（那里只有 composer.json 和 README） - 很多包发布时删减了 PHPDoc 注释（如只保留
src/，不带完整@throws），生成结果可能字段为空或缺失参数说明 - 别加整个
vendor/：扫描几百个包会卡死，且大量重复类名（如多个Stringable实现）引发冲突警告
composer run docs 失败常见原因
命令执行中断、输出空白、HTML 页面打不开——多数不是 phpdocumentor 本身的问题，而是环境或配置疏漏：
-
vendor/bin/phpdoc权限不足：Linux CI 环境常出现，加chmod -R a+r docs/api到 scripts 后续步骤 - PHP 版本不匹配：v3 要求 PHP ≥ 7.4；若用 PHP 8.2 运行 v2，会报
Attribute语法错误（#[\Deprecated]不识别） - 注释写错导致静默跳过：比如
@param string $foo少了变量名，或@return后没跟类型，phpdocumentor 不报错但不收录该方法 - 脚本中用了
2>&1屏蔽 stderr：掩盖了真实错误，比如找不到phpdoc.xml或路径不存在
真正难的不是跑通第一次生成，而是让文档持续可信——只要改了 public function process(array $data): bool 却忘了更新 @param 类型或 @return 描述，下一个人看文档就踩坑。没人会检查 HTML 页面是否过期，但所有人都会信它。
