通过集成phpDocumentor或Sami到Composer scripts可自动化生成API文档；需正确配置源码路径（如src/）、输出目录、缓存权限，并依赖完整PHPDoc注释，配合CI/CD实现提交即构建与部署。
直接用 phpdocumentor 或 sami 生成，别手写 HTML 或 Markdown —— 手动维护的文档在包迭代中必然脱节，而这两者能从 PHPDoc 注释里自动提取结构化信息，且与 Composer 脚本天然契合。
phpdocumentor 配置必须指定 src/ 而非 ./
常见错误是配置 <directory source-path=".">，结果把 tests/、vendor/、docs/ 全扫进去了，生成大量无关类、报错或文档体积暴涨。它默认不递归排除，得靠路径约束。
-
src/是标准包结构起点，所有公开 API 应在此目录下，命名空间也应匹配（如MyVendorMyPackage→src/） - 若用 PSR-4 自动加载，确保
composer.json中"autoload": { "psr-4": { "MyVendor\MyPackage\": "src/" } }已声明，否则phpdocumentor可能跳过文件（它依赖 autoloader 解析类） - 配置文件
phpdoc.dist.xml中的<output target="./docs/api"/>建议用相对路径，避免 CI 环境因绝对路径失败
sami.conf.php 的 build_dir 不能和源码同级
比如设成 __DIR__ . "/docs/api" 没问题，但若写成 __DIR__ . "/api"，Sami 构建时会清空整个 api/ 目录 —— 如果你手动放了 index.html 或自定义 CSS，全被删掉。这不是 bug，是它的设计逻辑：构建即覆盖。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 缓存目录
cache_dir必须可写，CI 中常因权限报错，建议设为__DIR__ . "/var/cache/sami"并在.gitignore里加/var/ -
default_opened_level设为2比1更实用：类方法默认展开，不用点三级菜单才看到参数说明 - Sami 不解析
@OA*注解，只认传统 PHPDoc（@param、@return），所以别指望它渲染 OpenAPI 接口描述
composer.json scripts 里别直接写长命令
像 "docs": "phpdoc -d src -t docs/api --template=clean" 看似简洁，但一旦要加 --title、--force 或换模板，命令迅速失控，且无法跨平台（Windows 下空格路径易崩）。
- 统一用配置文件驱动：
"docs": "phpdoc"，靠phpdoc.dist.xml控制行为，团队协作时改一处生效 - 加个
docs:check脚本验证注释完整性："docs:check": "php -r "foreach (glob('src/**/*.php') as $f) { if (!preg_match('/\\*\s+@param|@return/', file_get_contents($f))) echo "Missing doc in $f\n"; }""，提前发现漏写 PHPDoc 的方法 - 发布前跑
composer run docs应该是 CI 流程一环，但生成的docs/api/不提交到 Git —— 放 GitHub Pages 或静态托管更安全
真正难的不是生成文档，而是让每个 public 方法都带完整 PHPDoc：参数类型、返回值、异常、副作用。没这个基础，再好的工具也只产出空架子。别跳过 @throws，尤其当你的包抛 InvalidArgumentException 或自定义异常时 —— 用户靠这个判断是否要 try/catch。
