1. 什么是phpDocumentor ?
PHPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档。老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。
PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,然后分析注释中的专用的tag,生成 xml文件,接着根据已经分析完的类和模块的信息,建立相应的索引,生成xml文件,对于生成的xml文件,使用定制的模板输出为指定格式的文件。
2. 安装phpDocumentor
和其他pear下的模块一样,phpDocumentor的安装也分为自动安装和手动安装两种方式,两种方式都非常方便:
a. 通过pear 自动安装
在命令行下输入
pear install PhpDocumentor
b. 手动安装
在http://manual.phpdoc.org/下载最新版本的PhpDocumentor(现在是1.4.0),把内容解压即可。
3.怎样使用PhpDocumentor生成文档
命令行方式:
在phpDocumentor所在目录下,输入
Php –h
会得到一个详细的参数表,其中几个重要的参数如下:
-f 要进行分析的文件名,多个文件用逗号隔开
-d 要分析的目录,多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式,结构为输出格式:转换器名:模板目录。
例如:phpdoc -o HTML:frames:earthli -f test.php -t docs
Web界面生成
在新的phpdoc中,除了在命令行下生成文档外,还可以在客户端浏览器上操作生成文档,具体方法是先把PhpDocumentor的内容放在apache目录下使得通过浏览器可以访问到,访问后显示如下的界面:
点击files按钮,选择要处理的php文件或文件夹,还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
然后点击output按钮来选择生成文档的存放路径和格式.
最后点击create,phpdocumentor就会自动开始生成文档了,最下方会显示生成的进度及状态,如果成功,会显示
Total Documentation Time: 1 seconds
done
Operation Completed!!
然后,我们就可以通过查看生成的文档了,如果是pdf格式的,名字默认为documentation.pdf。
4.给php代码添加规范的注释
PHPDocument是从你的源代码的注释中生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。
从这一点上讲,PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
在phpdocumentor中,注释分为文档性注释和非文档性注释。
所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.
那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。
3.2如何书写文档性注释:
所有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。 PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
在功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能,用途,如果可能,也可以有用法举例等等。在这部分,你应该着重阐明你的API函数或者方法的通常的用途,用法,并且指明是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意事项或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。
之后同样是一个空白行,然后是文档的标记tag,指明一些技术上的信息,主要是最主要的是调用参数类型,返回值极其类型,继承关系,相关方法/函数等等。
关于文档标记,详细的请参考第四节:文档标记。
文档注释中还可以使用例如<b> <code>这样的标签,详细介绍请参考附录二。
下面是一个文档注释的例子
/**
* 函数add,实现两个数的加法
*
* 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
*
* @param int 加数
* @param int 被加数
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}
生成文档如下:
Add
integer Add( int $a, int $b)
[line 45]
函数add,实现两个数的加法
Constants 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
Parameters
• int $a - 加数
• int $b - 被加数
5.文档标记:
文档标记的使用范围是指该标记可以用来修饰的关键字,或其他文档标记。
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
@access
使用范围:class,function,var,define,module
该标记用于指明关键字的存取权限:private、public或proteced
@author
指明作者
@copyright
使用范围:class,function,var,define,module,use
指明版权信息
@deprecated
使用范围:class,function,var,define,module,constent,global,include
指明不用或者废弃的关键字
@example
该标记用于解析一段文件内容,并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容
@const
使用范围:define
用来指明php中define的常量
@final
使用范围:class,function,var
指明关键字是一个最终的类、方法、属性,禁止派生、修改。
@filesource
和example类似,只不过该标记将直接读取当前解析的php文件的内容并显示。
@global
指明在此函数中引用的全局变量
@ingore
用于在文档中忽略指定的关键字
@license
相当于html标签中的<a>,首先是URL,接着是要显示的内容
例如<a href=”http://www.baidu.com”>百度</a>
可以写作 @license http://www.baidu.com 百度
@link
类似于license
但还可以通过link指到文档中的任何一个关键字
@name
为关键字指定一个别名。
@package
使用范围:页面级别的-> define,function,include
类级别的->class,var,methods
用于逻辑上将一个或几个关键字分到一组。
@abstrcut
说明当前类是一个抽象类
@param
指明一个函数的参数
@return
指明一个方法或函数的返回指
@static
指明关建字是静态的。
@var
指明变量类型
@version
指明版本信息
@todo
指明应该改进或没有实现的地方
@throws
指明此函数可能抛出的错误异常,极其发生的情况
上面提到过,普通的文档标记标记必须在每行的开头以@标记,除此之外,还有一种标记叫做inline tag,用{@}表示,具体包括以下几种:
{@link}
用法同@link
{@source}
显示一段函数或方法的内容
6.一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool...)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释,提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明
7. 总结
phpDocumentor是一个非常强大的文档自动生成工具,利用它可以帮助我们编写规范的注释,生成易于理解,结构清晰的文档,对我们的代码升级,维护,移交等都有非常大的帮助。
关于phpDocumentor更为详细的说明,可以到它的官方网站
http://manual.phpdoc.org/查阅
8.附录
附录1:
能够被phpdoc识别的关键字:
Include
Require
include_once
require_once
define
function
global
class
附录2
文档中可以使用的标签
<b>
<code>
<br>
<kdb>
<li>
<pre>
<ul>
<samp>
<var>
附录三:
一段含有规范注释的php代码
<?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver <cellog@php.net>
* @version 1.0
* @package sample
*/
// sample file #1
/**
* Dummy include value, to demonstrate the parsing power of phpDocumentor
*/
include_once 'sample3.php';
/**
* Special global variable declaration DocBlock
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* Constants
*/
/**
* first constant
*/
define('testing', 6);
/**
* second constant
*/
define('anotherconstant', strlen('hello'));
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional')
{
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
/**
* The first example class, this is in the same package as the
* procedural stuff in the start of the file
* @package sample
* @subpackage classes
*/
class myclass {
/**
* A sample private variable, this can be hidden with the --parseprivate
* option
* @access private
* @var integer|string
*/
var $firstvar = 6;
/**
* @link http://www.example.com Example link
* @see myclass()
* @uses testing, anotherconstant
* @var array
*/
var $secondvar =
array(
'stuff' =>
array(
6,
17,
'armadillo'
),
testing => anotherconstant
);
/**
* Constructor sets up {@link $firstvar}
*/
function myclass()
{
$this->firstvar = 7;
}
/**
* Return a thingie based on $paramie
* @param boolean $paramie
* @return integer|babyclass
*/
function parentfunc($paramie)
{
if ($paramie) {
return 6;
} else {
return new babyclass;
}
}
}
/**
* @package sample1
*/
class babyclass extends myclass {
/**
* The answer to Life, the Universe and Everything
* @var integer
*/
var $secondvar = 42;
/**
* Configuration values
* @var array
*/
var $thirdvar;
/**
* Calls parent constructor, then increments {@link $firstvar}
*/
function babyclass()
{
parent::myclass();
$this->firstvar++;
}
/**
* This always returns a myclass
* @param ignored $paramie
* @return myclass
*/
function parentfunc($paramie)
{
return new myclass;
}
}
?>
- 浏览: 85777 次
- 性别:
- 来自: 苏州
文章分类
最新评论
-
lcwen_13:
你的很多代码都完全没有必要,实现太麻烦了!
Shiro系列之Shiro+Spring MVC整合(Integration) -
禹爸爸:
endual 写道牛逼的表达能力!!!代码全部用到项目中。分享 ...
使用Spring框架实现文件上传 -
endual:
牛逼的表达能力!!!代码全部用到项目中。
使用Spring框架实现文件上传 -
禹爸爸:
despair1989 写道请检查一下附录里的链接地址。链接地 ...
Mybatis系列之实战篇(上) -
despair1989:
请检查一下附录里的链接地址。链接地址错了
Mybatis系列之实战篇(上)
发表评论
-
PHP如何将表单提交给自己
2007-10-25 14:50 374使用PHP进行Web开发,表单(Form)的使用随处可见,利 ... -
PHP对HTML编码字符串的处理
2007-10-26 10:53 435今天在写一个PHP脚本访问数据库时,发现其中的中文字符串使用 ... -
Windows下PHP与Apache的安装与配置
2007-10-29 10:52 556在这里以PHP5为例介绍一下Windows下的PHP与Ap ... -
PHP中单引号与双引号的区别
2007-10-31 16:11 358在PHP中,可以使用单引号或是双引号来定义一个字符串。在平常 ... -
五种常见的PHP设计模式
2007-11-16 16:03 315工厂模式 最初在设计模式 一书中,许多设计模式都鼓励使用松 ... -
CodeIgniter类库之Calendar Class
2007-11-22 11:46 379CodeIgniter作为一款优秀的PHP开源框架,提供了相 ... -
CodeIgniter类库之Benchmarking Class
2007-11-22 23:47 378CodeIgniter中有个Benchmarking类库,它 ... -
CodeIgniter类库之Profiler Class
2007-11-26 20:01 357在之前有讲到Benchmarkin ... -
MSSQL数据库中Text类型字段在PHP中被截断之解
2008-01-03 21:11 695在PHP中使用了MSSQL数据库,恰巧数据库中又使用了Tex ... -
CodeIgniter类库之Validation Class(续)
2008-02-20 11:50 419在之前的一篇文章《CodeIgniter类库之Validat ... -
PHP日期操作
2008-06-14 01:15 329//返回指定月份的第一天 function g ... -
Zend Framework 视图中使用视图
2008-10-08 20:10 408<!DOCTYPEhtml PUBLIC&quo ... -
Zend Framework模块目录结构
2008-10-08 22:26 408在使用Zend Framework编写 ... -
Zend Framework之Layout
2008-11-06 19:35 517为了让不同的View以相同的布局进行显示,我们可以编写布局模 ... -
PHP调用MS SQL 存储过程
2008-12-23 17:00 478在PHP中调用MS SQL存储过程 functiong ... -
PHP中Ajax中文乱码问题解决
2009-02-27 09:27 321最近在编写的PHP项目中用到了Ajax技术,用户体验大有提升 ... -
PHP获取类中常量,属性,及方法列表的方法
2009-04-07 16:53 433PHP获取类中常量,属性,及方法列表的方法 ... -
PHP 中巧用数组降低程序的时间复杂度
2009-12-04 09:17 363在CSDN上看到这篇文章 ... -
PHP导出Excel
2010-11-20 23:21 391无比风骚的PHPExcel,官方网站: http://www ...
相关推荐
【代码注释规范】 phpDocumentor依赖于规范化的代码注释来生成文档。注释分为文档性注释和非文档性注释。文档性注释是放置在特定关键字(如"class", "var"等)前的多行注释,包含了功能简述区、详细说明区和标记tag...
在IT领域,PDP(Portable Document Package)是一种常见的文件格式,用于存储和传递文档。PDP文件通常包含一个或多个文档、图像和其他资源,使得用户可以在不依赖原始创建软件的情况下查看和打印内容。而提到“非常...
PDP 上下文激活详细分析 PDP(Packet Data Protocol,分组数据协议)是一种用于无线通信网络中的数据传输协议。MS(Mobile Station,移动站)发起的 PDP 上下文激活是指 MS 向 SGSN(Serving GPRS Support Node,...
### 多个PDP上下文在UMTS中的应用 #### 引言 ##### 本文档的目的 本白皮书旨在介绍UMTS网络中多个PDP上下文的应用。它详细解释了多个主PDP上下文(Primary PDP Contexts)和次级PDP上下文(Secondary PDP Contexts...
PDP-11是一款由美国数字设备公司(Digital Equipment Corporation,简称DEC)在1970年代推出的16位中型计算机。它在当时是一个划时代的计算机产品,尤其在小型机市场占有重要地位,其设计具有许多创新特性,而且非常...
### ATTACH&PDP_激活流程 #### 移动通信中各设备间的激活流程概述 在移动通信领域,尤其是GPRS(General Packet Radio Service,通用分组无线服务)网络中,移动终端(MS,Mobile Station)与网络之间的交互过程至...
例如,当用户提交答案时,JavaScript代码会收集这些信息并存储到小程序的全局变量或缓存中。 在实现测试逻辑时,开发者需要创建一个模型来存储每个问题及其可能的答案,以及对应的得分规则。测试结束后,根据用户的...
销售预测系统PDP系统源代码资料
**原始版 PDP UNIX V7** 是计算机操作系统历史上的一个重要里程碑,它是由贝尔实验室(Bell Labs)在20世纪70年代开发的。这个版本的UNIX系统是基于PDP-11架构的,并且对后来的UNIX发展产生了深远影响。在深入探讨其...
PDP8-Emulator 是一个基于汇编语言的模拟器,专为运行PDP8(Programmed Data Processor Model 8)计算机系统上的代码而设计。PDP8是1960年代初由Digital Equipment Corporation(DEC)推出的一种小型、早期的商业...
PDP即等离子体显示器技术是利用气体放电产生的紫外线激发荧光粉,产生可见光的一种显示技术。根据其工作方式,PDP主要分为直流型和交流型两大类。其中,交流型PDP以其优良的性能被广泛应用在彩色显示器领域。按照...
### PDP原理详解 #### 一、等离子体概述 等离子体作为一种物质的状态,在自然界中广泛存在且具有重要的物理意义。它不仅存在于宇宙空间之中,还在地球上的许多自然现象中发挥着作用,如闪电、极光等。等离子体是由...
- 统计显示,8月份PDP激活返回代码中,成功代码0x0占比63.43%,失败代码0x21(33)占比36.51%,这表明终端设置错误或APN未签约是主要的失败原因。 - 其中,iPhone和黑莓等智能终端的内置客户端自动发起连接,尤其...
ppp 相当于链路层协议 socket 套接字,对 tcp/ip 协议的封装、应用 gprs 上网首先要设置 pdp,接着建立 ppp 连接,ppp 连接建立后,就可以进行 tcp/ip 传输了, 要进行 tcp/ip 数据传输,很多时候都采用 socket PDP...
去除PDP口令
一键激活PDP ADB模式 非常好用 不需要root 一键激活PDP ADB模式 非常好用 不需要root
PDP-11为美商迪吉多电脑(Digital Equipment Corp.)於1970到1980年代,所销售的一系列16位元 迷你电脑 。PDP-11是迪吉多电脑的PDP-8系列的后续机种。PDP-11有着许多创新的特色,而且比起其前代机种更容易撰写程式。当...
该文档介绍了多PDP上下文,是一个很好的入门课程,值得推荐