Composer项目无内置安装文档字段，有效说明应放根目录README.md；description仅作Packagist摘要，scripts可封装带注释的可执行命令，autoload与文档生成无关。
composer.json 里不能放安装文档
Composer 不解析 composer.json 中的长文本字段作文档用途。很多人误把 description 或 support 当成写安装步骤的地方，结果在 Packagist 上只显示前 120 字，还带截断省略号。真实有效的项目说明必须放在根目录的 README.md——GitHub、GitLab、Packagist 页面和 PHPStorm 都会自动渲染它，用户打开仓库第一眼就看到。
若想让命令可执行又带说明，唯一靠谱的方式是用 scripts 字段封装，并在注释里写清楚用途。比如：
"scripts": {
"docs:install": [
"echo "? Installs dev dependencies + generates API docs"",
"composer install --dev",
"php vendor/bin/apigen generate --source=src --destination=docs/api"
]
}
然后用户只需运行 composer run-script docs:install，就能看到提示并执行完整流程。
autoload 不等于文档生成入口
autoload 字段只控制类文件如何被 PHP 自动加载，跟生成 API 文档完全无关。填错路径不会报错，但会导致 Class not found；而文档工具（如 ApiGen、phpDocumentor）需要的是源码路径、注释格式、输出目标等独立配置。
常见误区包括：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 以为加了
"psr-4": {"App\": "src/"}就能自动生成接口列表——不能，这只是告诉 Composer 哪里找类 - 把
autoload-dev当成“开发文档开关”——它只是加载测试类，不影响文档生成 - 没检查 PHP 扩展是否启用（如
tokenizer、xml），导致 phpDocumentor 启动失败但报错模糊
用 phpDocumentor 生成 API 手册的最小可行路径
phpDocumentor 是目前最稳定的 PHP 文档生成器，支持 PHP 8.2+，且不依赖 Composer 的 autoload 配置。
实操要点：
- 安装：运行
composer require --dev phpdocumentor/phpdocumentor（注意加--dev） - 配置：在项目根目录建
phpdoc.xml，至少包含<paths><source>src/</source></paths> - 执行：运行
vendor/bin/phpdoc run，默认输出到build/docs - 关键限制：它只解析符合 PHPDoc 标准的注释（
/** ... */），不识别//行注释或无格式描述
如果项目里大量函数没写 PHPDoc，生成的页面会空荡荡——这不是工具问题，是注释缺失。
为什么 vendor 目录不该进文档生成范围
所有文档工具默认跳过 vendor/，这是硬编码行为。强行加入会导致：
- 生成时间暴增（TCPDF、monolog 等库有上千个类）
- 输出体积失控（单次生成可能超 500MB）
- 版本污染：不同项目依赖同一包的不同版本，生成的“API 手册”实际是混合体，失去参考价值
真正要文档化的，只有你自己的 src/（或 lib/、app/）目录。第三方库的文档应直接查其官网或 Packagist 页面。
