PHPDocumentor安装与使用-阿里云开发者社区

开发者社区> 开发与运维> 正文
登录阅读全文

PHPDocumentor安装与使用

简介: PHPDocumentor 是一个用PHP写的工具, 对于有规范注释的php程序, 它能够快速生成具有相互参照,索引等功能的API文档. 安装环境: 本机安装的是 EasyPHP-5.3.2i 套件, 1 安装目录是 D:\Program Files\EasyPHP-5.3.2i\ 2 php.exe 所在路径是 D:\Program F


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

安装环境:
本机安装的是 EasyPHP-5.3.2i 套件,

1 安装目录是 D:\Program Files\EasyPHP-5.3.2i\
2 php.exe 所在路径是 D:\Program Files\EasyPHP-5.3.2i\php\php.exe

首先安装 PEAR:
1, 修改 D:\Program Files\EasyPHP-5.3.2i\php\go-pear.bat 内容如下:

1 @ECHO OFF
2 set PHP_BIN=%CD%\php.exe
3 "%PHP_BIN%" -d output_buffering=0 -d phar.require_hash=0 PEAR\go-pear.phar
4 pause

2, 开始->运行->cmd, 执行 go-pear.bat 开始安装 Pear, 一路回车

1 Microsoft Windows XP [版本 5.1.2600]
2 (C) 版权所有 1985-2001 Microsoft Corp.
3  
4 C:\Documents and Settings\kuco>D:
5  
6 D:\>cd D:\Program Files\EasyPHP-5.3.2i\php
7  
8 D:\Program Files\EasyPHP-5.3.2i\php>go-pear.bat

3, 修改 php.ini 中的 include_path

1 include_path = ".;${path}\php\includes;${path}\php\PEAR"

4, EasyPHP 套件中的 php.ini 没有存放在 php.exe 所以目录中,所以要复制一份.

1 复制 D:\Program Files\EasyPHP-5.3.2i\apache\php.ini
2   到 D:\Program Files\EasyPHP-5.3.2i\php\ 目录下

开始安装 PhpDocumentor:
5, 安装 PhpDocumentor 依赖包 XML_Parser

1 D:\Program Files\EasyPHP-5.3.2i\php>pear install XML_Parser
2 downloading XML_Parser-1.3.4.tgz ...
3 Starting to download XML_Parser-1.3.4.tgz (16,040 bytes)
4 ......done: 16,040 bytes
5 install ok: 

6, 安装 PhpDocumentor

1 D:\Program Files\EasyPHP-5.3.2i\php>pear install PhpDocumentor
2 Did not download optional dependencies: pear/XML_Beautifier, use --alldeps to do
3 wnload automatically
4 pear/PhpDocumentor can optionally use package "pear/XML_Beautifier" (version >=
5 1.1)
6 downloading PhpDocumentor-1.4.3.tgz ...
7 Starting to download PhpDocumentor-1.4.3.tgz (2,423,486 bytes)
8 ......done: 2,423,486 bytes
9 install ok: 

使用 PhpDocumentor 生成注释文档
7, 假设我们要给 Smarty 的源码包生成一个注释文档

1 Smarty 源码存放目录为: E:\www\IDE\Smarty\libs\
2 注释文档存放的目录为: E:\www\IDE\doc
3 开始在命令行执行命令:
4 D:\Program Files\EasyPHP-5.3.2i\php>phpdoc.bat -o HTML:Smarty:PHP -d E:\www\IDE\Smarty\libs\ -t E:\www\IDE\doc

可以通过下面的命令得到更多的帮助说明

1 D:\Program Files\EasyPHP-5.3.2i\php>phpdoc -h




在phpdoc.bat所在目录下,输入

Phpdoc –h


会得到一个phpDocumentor的详细参数列表。

我们从其中选出几个常用的来看看:

〈? 命令解释 ?〉

-f 
要进行分析的文件名,多个文件用逗号分割

-d 
要分析的目录,多个目录用逗号分割

-t 
生成的文档的存放路径

-o 
输出的文档格式,结构为输出格式:转换器名:模版目录,例如:HTML:frames:phpedit  
 

我们会用到的就这几个了,其他的命令请大家阅读help的提示信息。

 

试用phpDocumentor

下面我们就以pear中的phpUnit2为例,演示一下如何使用phpDocumentor来生成文档。

首先,把我们需要的参数确定下来:

〈? 命令参数 ?〉

-d 
C:Program FilesEasyPHP5phpPEARPHPUnit2

-t 
C:Program FilesEasyPHP5phpphpunit2doc

-o 
HTML:frames:phpedit  
 


根据上边的参数,我们组合出下边的命令:

Phpdoc -d “C:\Program Files\EasyPHP5\php\PEAR\PHPUnit2” -t “C:\Program Files\EasyPHP5\php\phpunit2doc” -o “HTML:frames:phpedit”


运行上边的命令后,phpDocumentor开始解析源文件并输出工作信息。

 


命令运行完成后,我们的文档就已经生成好了。 进入我们指定的目标目录,用浏览器打开index.html就可以看见生成的文档了。 文档界面由frame分成了三个部分,左上是包信息,左下是导航信息,右边则是详细的信息呈现页。

 


上边的图很清楚地描述出了文档的内容:

索引、函数列表、类列表、文件列表和子包。

点击上边的class(es)链接,我们可以清晰的看见整个包的class tree。

 


我们点击其中一个class,就进入了class的描述页面。

Class描述页面主要包含以下几方面内容:

 

l 描述:版权、作者、类层次等

l 类变量

l 类常量

l 方法

l 继承的变量

l 继承的方法:非常有用的一个功能

 

 


怎么样,是不是很详细呢?如果要生成chm,可以把前边的-o参数改为”CHM:default: default”,这样phpDocumentor会为你生成好chm项目文件,只要用微软的chm工具进行编译就可以得到可用的chm文件了。

 

用phpDocumentor为自己的代码生成文档

虽然phpDocumentor可以自动从代码中分析出一些信息,但是,要形成一份详尽的文档还是需要我们在编码中进行配合的。为了让phpDocumentor读懂我们的代码,我们需要注意一些编码规范和在注释中增加一些tag:

 

〈? Tags ?〉

@author 
作者信息

@const 
由define定义的常量

@deprecate 
不建议使用的API

@global 
全局变量

@package 
包信息

@param 
函数参数

@return 
返回值

@see 
参考函数

@since 
引入时间

@static 
静态变量

@var 
类成员变量  
 

 


这里只是简单的列出了常用的一些Tag,大家可以阅读phpDocumentor的文档,里边有非常详细的编码规范。关于phpDocumento就介绍到这里,希望大家都能好好利用这个工具来规范自己的文档。

 

PS:phpDocumentor也有Web界面的,你可以访问http://phpdoc.org获取Web版本。Web版本的安装很简单,直接放到web可以访问的目录就可以运行了。

 

〈? 环境要求 ?〉


版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章
最新文章
相关文章