PHPDoc/PHPDocumentor生成API文档

原创 2015年11月18日 22:22:28

PHPDocumentor是一个用PHP写的强大的文档自动生成工具,对于有规范注释的php程序,能够快速生成具有结构清晰、相互参照、索引等功能的API文档。旧版本是PHPDoc,PHPDoc是PEAR下面的一个非常优秀的模块,类似于javadoc。从1.3.0开始,更名为phpDocumentor,新版本新加了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF、HTML、CHM等格式的文档,这样非常有利于代码的升级、维护、移交等。

前提:安装的前提是已经安装了php环境,我安装的是xampp集成开发环境。

1.PHPDoc的结构及功能
PHPDoc是全部采用OOP的思想来编写的,这也是PEAR所推荐的方式,PHPDoc的工作原理:PHPDoc扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,然后分析注释中的专用的tag,生成xml文件,接着根据已经分析完的类和模块的信息,建立相应的索引,生成xml文件对于生成的xml文件,使用定制的模板输出为html文件。从设计上来说,PHPDoc使用了2个超类:PhpdocObject和PhpdocError。这是整个PHPDoc的基本类,这种方式也是PEAR所推荐的。当你编写应用框架时,最好能够有一个基本的超类,而其他的子类或者是功能类都有一个共同的祖先。在扫描源代码过程中,PHPDoc使用的是类似GREP的形式。PHPDoc令人满意的另一方面是其分析结果是以XML形式保存的,这就意味着其他应用程序可以共享这个数据,同时PHPDoc也提供了相应的接口,你可以实现这个接口,把API文档生成其他的形式,比如PDF,LATEX,WORD等。目前,PHPDoc的分析结果可以以HTML形式表现,由于使用了模板机制,可以很方便地定制风格。

2.安装PHPDoc
安装方式有两种,一是下载源码安装,另一种是通过pear安装。

第一种方法:
第一步:安装pear
使用dos窗口进入php安装目录,有个文件叫go-pear.bat,如果没有,建议到网上下载go-pear.phar,然后在dos窗口下运行 go-pear.phar, 从而安装pear。

php go-pear.phar 

第二步:安装phpdoc

Pear install phpDocumentor 

在phpDocumentor成功安装后,php安装目录下会多出来一个phpdoc.bat。这个文件就是我们用来生成文档的批处理文件。
在phpdoc.bat所在目录下,输入

Phpdoc –h 

会得到一个phpDocumentor的详细参数列表。先看看最重要的几个吧。

-d  
这个目录代表着需要生成文档的原始php文件目录(注意是目录) 
-t  
这个目录代表着生成的文档存放目录
-o  
这个参数代表着生成的文档格式,例如html格式,参数就是
HTML:frames:phpedit

第三步:生成文档
生成文档的命令就是:

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1"  -o "HTML:frames:phpedit"

生成的html文件

可以看到,解析完成后,在目标目录下生成很多html文件,打开index.html文件,就是我们需要的文档,如下图所示。

生成的类参考文档

第二种方法:
第一步:下载PHPDoc压缩文件(phpdoc.zip),地址如下:
http://star7th-wordpress.stor.sinaapp.com/uploads/2013/04/phpdoc.zip

第二步:解压到某一个目录
打开phpdoc.bat,编辑第16行:

SET phpCli=D:\xampp\php\php.exe

配置phpCli 为自己php.exe文件的路径即可。

第二步:dos窗口,进入文件的解压目录,然后执行解析文档命令即可。

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1"  -o "HTML:frames:phpedit"

以上是安装phpDocumentor1版本,目前已经更新到phpDocumentor2版本了,version2的安装也很简单。

第一步:安装pear(同上)
此处给出下载地址:http://pear.php.net/go-pear.phar
将 go-pear.phar 放到 PHP 目录下执行安装命令:

php go-pear.phar

下面会执行输入 system

然后一路回车安装完毕。

第二步:接下来安装类关系绘图用到的工具

pear install image_graphviz
下载 http://www.graphviz.org/Download_windows.php graphviz-2.38.msi
安装后,注意环境变量 path 添加上该 bin 的路径,重启电脑,否则无法生效

第三步:安装 phpDocumentor

pear channel-discover pear.phpdoc.org 
pear install phpdoc/phpDocumentor

稍等一会,安装步骤完成!
注意:两个软件安装后的目录都在PHP 下的 pear 下面:

php/pear/PhpDocumentor
php/pear/Image

显然:version2 比version1速度快了很多。

版权声明:本文为博主原创文章,未经博主允许不得转载。

相关文章推荐

swagger 生成 PHP restful API 接口文档

需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用 swagger 前手写文档的血泪史. 我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪史中...

Delphi7高级应用开发随书源码

  • 2003年04月30日 00:00
  • 676KB
  • 下载

使用phpdoc/phpDocumentor来生成api文档

使用phpdoc/phpDocumentor来生成api文档

Swagger-PHP 自定义生成API

从此接口文档成为一笑而过,从此服务端不再被客户端追债似得要接口文档 主要内容: 1、项目背景 2、Swagger应用 3、总结 项目背景           作为一...

JS 根据今天的日期获取本周星期一与星期天的日期

var now = new Date();  var nowTime = now.getTime() ;  var day = now.getDay(); var oneDayLong = 24*60...

使用phpdoc/phpDocumentor来生成api文档

  • 2015年04月27日 13:15
  • 2.01MB
  • 下载

phpdoc/phpdocumentor注释规范

phpDocumentor通过解析PHP代码逻辑结构(如文件,类,函数,常量,全局变量,类成员/方法等),重新整理后生成普通的可读说明文档。一、给php代码添加规范的注释 PHPDocument是从...

有关PHP文档生成工具---PHPDocumentor

1. 什么是phpDocumentor ? PHPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档。老的版本是 phpdoc,...

怎样使用PhpDocumentor生成文档

命令行方式:   在phpDocumentor所在目录下,输入 phpdoc –h   会得到一个详细的参数表,其中几个重要的参数如下: -f 要进行分析的文件名,多个文件用逗号隔开 -d ...

使用phpdocumentor2生成项目文档

phpdocumentor2简述在开发一个大型的项目中,项目文件往往会越来越多,这时如果我们寻找一个类文件,想知道他的功能时,可能需要到一个很深的目录结构中去寻找,而且我们很多时候并不是想研究这个类文...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:PHPDoc/PHPDocumentor生成API文档
举报原因:
原因补充:

(最多只允许输入30个字)