PHP文档生成器（PHPDoc）的基本用法

目录

• PHP文档生成器（PHPDoc）的基本用法
• PHPDoc概述
• 安装
• PHPDoc注释规范
  • 页面级别的注释
  • 代码级别的注释
• 生成API文档
• 额外软件

PHP文档生成器（PHPDoc）的基本用法

PHPDoc概述

PHPDoc是一种注释PHP代码的正式标准，一般是通过外部文档生成器phpDocumentor生成API文档。同事支持面向过程和面向对象的代码风格，而且很多高级IDE如PHPStorm对其有很好的支持。灵活使用PHPDoc生成API文档可以有效提高开发效率，本文主要是记录PHPDoc的基本用法。

安装

PHPDoc官方提供三种安装方式，分别是通过pear、composer和phar进行安装。Linux通过pear安装phpdoc比较简单，只需按照官方引导即可。composer主要针对项目，需要注意的是composer安装phpdoc会引入很多依赖包。phar方式需要下载phpDocumentor外部文档，然后在终端通过php-cli进行调用即可。本文采用了第三种方法，这种方法可以兼容各操作系统，并且不需要安装额外软件。

PHPDoc注释规范

页面级别的注释

一般来说，页面级的文档块就是文件中出现的第一个文档块，推荐使用@package标签对文件路径进行标注。

代码级别的注释

代码级别主要指类、变量和方法的注释块，其中方法的参数值和返回值注释与PHP的数据类型基本相同。需要注意PHPDoc不支持对单行注释的解析，所以需要使用代码块。

生成API文档

php phpDocumentor.phar -d Pro/ -t docs/api

-d后面跟文件夹路径，如果是单个文件，可以用-f。-t表示目标target，后面跟API文档生成的文件夹。如果需要指定模板，可以在代码后面追加--template。

php phpDocumentor.phar -d Pro/ -t docs/api --template="clean"

可以通过template:list查看所支持的内置模板

php phpDocumentor.phar template:list

可以直接在template后面接自定义模板

php phpDocumentor.phar -d Pro/ -t docs/api --template="data/template/my_template"

额外软件

• 如果需要查看类的图表，需要安装Graphviz。以ubuntu为例

sudo apt-get install graphviz