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速度快了很多。

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

使用phpdoc/phpDocumentor来生成api文档

使用phpdoc/phpDocumentor来生成api文档
  • wuchengzeng
  • wuchengzeng
  • 2015年04月27日 13:10
  • 4463

如何使用phpdoc生成PHP文档

如何使用phpdoc生成PHP文档
  • rcom10002
  • rcom10002
  • 2010年08月12日 08:53
  • 2765

使用phpdoc/phpDocumentor来生成api文档

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

PHPWord,可以自动生成doc文档

  • 2016年07月12日 10:05
  • 148KB
  • 下载

PHP 文件操作类(创建文件并写入) 生成日志

  • homevip
  • homevip
  • 2014年06月01日 22:14
  • 1956

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

PHPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档。老的版本是 phpdoc,从1.3.0开始,更名为phpDocumen...
  • ltx851201
  • ltx851201
  • 2010年08月18日 13:45
  • 7468

用phpword导出word文档

//导出成交确认函 public function outputH(){ $start_time1 = strtotime($_POST['start_time1']); ...
  • ning521513
  • ning521513
  • 2017年02月16日 14:14
  • 1867

php中如何把html中的内容生成到word文档

1:在php中如何把html中的内容生成到word文档中    2:php把html中的内容生成到word文档中时,不居中显示问题,即会默认按照web视图进行显示。 Word.class.php:...
  • lf747784476
  • lf747784476
  • 2016年12月01日 17:38
  • 2556

swagger 生成 PHP restful API 接口文档

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

Swagger-PHP 自定义生成API

从此接口文档成为一笑而过,从此服务端不再被客户端追债似得要接口文档 主要内容: 1、项目背景 2、Swagger应用 3、总结 项目背景           作为一...
  • wenanshi
  • wenanshi
  • 2016年08月10日 11:20
  • 7745
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:PHPDoc/PHPDocumentor生成API文档
举报原因:
原因补充:

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