·您的位置: 首页 » 资源教程 » 编程开发 » PHP » PHP文档工具

PHP文档工具

类别: PHP教程  评论数:0 总得分:0
写文档是一项乏味却不得不做的工作,而编写API级的文档更是意味着大量的重复劳动和难以保持的一致性。这里我们要推荐给大家的,是支持PHP5语法分析的文档工具――phpDocumentor。

使用phpDocumentor不仅可以自动从代码中提取出函数和方法定义,还可以自动处理各个class之间的关系,并据此生成class tree。你还可以选择将文档生成html、chm或者pdf。有了phpDocumentor,文档工作变得轻松了很多。



安装phpDocumentor

在pear下安装phpDocumentor是一件极其简单的事情,只需要在cmd窗口中cd 到php安装目录下,然后输入

Pear install phpDocumentor


Pear就会自己下载并完成phpDocumentor的安装。

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

<? 相关知识 ?>

phpDocumentor是phpDoc的升级版本,是专门为支持php5语法而重写的文档工具,当你的php版本为5时,运行phpDoc.bat,它会自动去调用phpDocumentor。所以文章中的提到的phpDoc和phpDocumentor实际上是相同的。




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

Phpdoc ?Ch


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

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

<? 命令解释 ?>

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

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

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

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




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



试用phpDocumentor

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

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

<? 命令参数 ?>

-d
C:/Program Files/EasyPHP5/php/PEAR/PHPUnit2

-t
C:/Program Files/EasyPHP5/php/phpunit2doc

-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可以访问的目录就可以运行了。



<? 环境要求 ?>

PHP:5.0.0

OS: 平台独立,本文演示OS为windows




-= 资 源 教 程 =-
文 章 搜 索
关键词:
类型:
范围:
纯粹空间 softpure.com
Copyright © 2006-2008 暖阳制作 版权所有
QQ: 15242663 (拒绝闲聊)  Email: faisun@sina.com
 纯粹空间 - 韩国酷站|酷站欣赏|教程大全|资源下载|免费博客|美女壁纸|设计素材|技术论坛   Valid XHTML 1.0 Transitional
百度搜索 谷歌搜索 Alexa搜索 | 粤ICP备19116064号-1