使用phpDocumentor从PHPDoc注释生成API文档，需为类、方法添加标准注释并配置composer.json，执行命令后输出静态文档。
为你的Composer包生成API文档，关键在于使用合适的工具从代码注释中提取信息并生成结构化的文档页面。PHP本身不自带文档生成器，但社区有成熟方案可以轻松实现。
选择合适的文档生成工具
主流的PHP文档生成器能解析代码中的PHPDoc注释，自动生成类、方法、参数等API说明：
-
• phpDocumentor：功能完整，支持最新PHP语法，输出美观，配置灵活。• Doxygen：跨语言支持，适合复杂项目，但界面较老。• ApiGen（已停止维护）：曾流行，但现在不推荐新项目使用。
推荐使用 phpDocumentor，它活跃维护且与Composer集成良好。
给代码添加标准PHPDoc注释
文档生成器依赖清晰的注释。确保每个类、方法、属性都有符合规范的PHPDoc块：
```php/** * 用户服务类，处理用户相关业务逻辑 */ class UserService { /** * 根据ID获取用户信息 * * @param int $id 用户唯一标识 * @return array|null 返回用户数组，未找到返回null * @throws InvalidArgumentException 当ID小于1时抛出 */ public function findById(int $id): ?array { if ($id
注意使用 @param、@return、@throws 等标签，类型和描述尽量准确。
安装并运行phpDocumentor
通过Composer在项目中本地安装：
```bash
composer require --dev phpdocumentor/phpdocumentor
然后执行生成命令：
```bash./vendor/bin/phpdoc.php run -d src -t docs/api
这会读取 src 目录下的代码，输出静态HTML文档到 docs/api。
你也可以创建 phpdoc.xml 配置文件来自定义标题、忽略文件、模板等。
自动化文档生成流程
为了保持文档及时更新，可将文档生成集成到开发流程中：
-
• 在
composer.json 中添加脚本：```json"scripts": { "docs": "phpdocumentor" }这样运行
composer docs 就能快速生成。• 使用GitHub Actions等CI工具，在每次提交后自动构建并部署文档到GitHub Pages。
基本上就这些。只要写好注释，用phpDocumentor跑一下，你的Composer包就有了专业API文档。不复杂但容易忽略的是持续维护注释准确性——文档过期比没有更误导人。
