使用 Composer scripts 可自动生成功能文档，通过安装 Doctum 并配置 doctum.php 定义源码路径与输出目录，在 composer.json 中添加 "docs:generate" 和 "docs:serve" 命令，执行 composer docs:generate 即可解析 PHP DocBlock 生成 HTML 文档，并可集成到 Git 钩子或 CI/CD 实现自动化更新。
使用 Composer scripts 自动生成文档是一种高效的方式，可以在代码变更后自动更新文档内容。Composer 本身支持自定义脚本命令，结合文档生成工具（如 PHPDocumentor、ApiGen 或 Doctum），能实现一键生成 API 文档或技术说明。
安装文档生成工具
以 Doctum 为例（PHPDocumentor 的现代分支），可通过 Composer 安装为项目依赖：
composer require --dev "codedungeon/doctum"安装完成后，可在项目根目录创建配置文件 doctum.php，定义文档源码路径和输出位置：
use Doctum\Doctum;use Symfony\Component\Finder\Finder;
$iterator = Finder::create()
->files()
->name('*.php')
->exclude('vendor')
->in(__DIR__ . '/src');
return new Doctum($iterator, [
'title' => 'My Project Documentation',
'build_dir' => __DIR__ . '/docs/build',
'cache_dir' => __DIR__ . '/docs/cache',
'version' => 'latest',
'title_footer' => 'Generated with Doctum',
]);
配置 Composer Scripts
在 composer.json 中添加自定义脚本，调用 Doctum 命令生成文档：
"scripts": {"docs:generate": "doctum generate",
"docs:serve": "doctum serve"
}
执行以下命令即可生成文档：
composer docs:generate
该命令会根据 doctum.php 配置扫描 src 目录下的 PHP 文件，解析 DocBlock 注释并生成静态 HTML 页面。
自动化文档更新流程
可将文档生成集成到开发流程中，例如：
- 在 Git 提交钩子中运行 composer docs:generate，确保每次代码提交后文档同步更新
- 配合 CI/CD 工具（如 GitHub Actions），在推送主分支时自动部署文档到 gh-pages
- 结合 PhpStorm 等 IDE 的外部工具设置，实现编辑器内一键生成预览
只要注释规范（使用 @param、@return、@throws 等标准标签），就能持续维护高质量的 API 文档。
基本上就这些。通过简单配置，让 Composer 脚本帮你把写代码和出文档变成一件事。不复杂但容易忽略。
