商务合作:179001057@qq.com

技术2022-05-11  0


某平台价值19860元的编程课程资料免费领取【点我领取】


四、 phpDocumentor关键字及文档标志

4.1 关键字class 、function 、var 、include (include_once, require, require_once) 、define

在以上这些关键字前面所做的注释,都被认为是文档性注释。

4.2 文档标记说明:使用范围是指该标记可以用来修饰的关键字,或其他文档标记@abstract 使用范围:class, function, var 说明当前类是一个抽象类。

注释:从PHP语言角度来说,它并不象JAVA,C++那样,支持抽象类这个概念。也没有相应的关键字来修饰某个类是抽象类。由于phpDocumentor实际上大部分是借鉴了JAVADOC的做法,因此很多文档标记也是直接从JAVADOC中沿袭过来,如abstract,access,final等等。虽然这些特性没有从语言级别得到支持,不过从使用者角度来遵循这些特性,仍是值得推荐的。

举例: /*** 这是一个绘五星图案的抽象类.* @abstract*/class paint_start {  /**  * 绘制数量  * @abstract  */  var $number;  /**  * 绘制五星图案  * @abstract  */  function paint() {

  }}

@access (public|private) 使用范围:class, function, var, define, module

指明这个变量、类、函数/方法的存取权限。如果你的函数是内部使用,你应该指明它为private,这样的好处是,即使PHP不能阻止其他的人使用你的私有数据,但是至少你向你的用户传达这样的信息,这是一个私有的函数,因此不保证在将来的版本中仍存在;对于使用者而言,表示为@private的数据和方法,你不应该直接使用,即使你可以这样做。

举例: /*** 这是一个绘五星图案的抽象类.* @abstract* @access public*/class paint_start {

  /**  * 绘制数量  * @abstract  * @access private  */  var $number;

  /**  * 绘制五星图案  * @abstract  * @access public  */  function paint() {

  }

}

@author Name [<email>] [, ...] 使用范围:class, function, var, define, module, use

指明作者信息,依次是作者姓名,email地址,其他的通讯信息。如果有多个作者,按照其先后次序,使用多个@author依次列出:

* @author Night Sailer <[email]night@hotmail.com[/email]> * @author Lee Tester <[email]tester@gnome.org[/email]> @brother (function()|$variable) 使用范围:class, function, var, define, module, use@sister (function()|$variable) 使用范围:class, function, var, define, module, use

指出兄弟类、函数或者是变量.这些函数、类、变量等有相似的信息和并实现相同的功能。比如,调用和返回的参数的个数和类型相同,实现的功能也一样。这种情况,你可以使用@brother 或者 @sister指明它的兄弟函数,无须在重复书写函数的功能等信息了。

举例: /*** 这是一个绘五星图案的抽象类.* @abstract* @access public*/class paint_start {

  /**  * 绘制数量  * @abstract  * @access private  */  var $number;

  /**  * 绘制五星图案  * @abstract  * @access public  */  function paint() {

  }

  /**  * @brother paint()   */  function draw() {

  }

}

@const[ant] label [description] 使用范围:define 指明常量 这个标记实际上是用来说明php的define关键字定义的常量。

@copyright description 使用范围:class, function, var, module, define, use 指明版权信息。

@deprec[ated] label 使用范围:class, function, var, module, define, use指明不推荐或者是废弃的信息.

如果你的某个函数或者方法,已经被新的函数方法替代,或者是已经废弃,不希望读者继续使用。那么你可以使用这个标志告诉读者,这个函数只是为了保持兼容性而保留的,它不被推荐使用,如果它已经被其他函数替代,也要指出这个替代者。

例子: /*** 过时的类** @deprec 1.5-2000/12/06* @access public*/function dontUseMeAnyMore() {  print "Don't use me any more. I have been deprecated.";}

@exclude label 使用范围:class, function, var, module, define, use 指明当前的注释将不进行分析,不出现在文挡中

@final 使用范围:class, function, var 指明这是一个最终的类、方法、属性,禁止派生、修改。 举例: /*** 圆周率 * @final*/var $PI = 3.1415926;

@global (object objecttype|type) [$varname] [description] 使用范围:function 指明在此函数中引用的全局变量举例: /*** Simuliert include_once in PHP 3.** @global array $used_files 已经include的文件列表* @access public*/function include_once($filename) {  global $used_files;

  if (!isset($used_files["include_once"][$filename])) {    $used_files["include_once"][$filename] = true;    include($filename);  }}

@include description 使用范围:use 指明包含的文件的信息。 举例: /*** 抽象绘图类的定义.** @include Function: require*/require("abstract.php");

@link URL description 使用范围:class, function, var, module, define, use 定义在线连接,如上面3.4中讲到的,你可以使用@link添加适当的在线链接。 例如:@link [url]http://www.phpDocumentor.de/[/url] PhpDocumentor Home

@magic description 这个标记在phpDocumentor中没有说明,具体用法现在仍不清楚

@module label 使用范围:module 定义归属的模块信息,label是模块的名字,拥有相同的模块名字的函数在索引分类中将被组合在一起。如果你没有使用OOP的思想来编写PEAR代码,那么建议你使用这个标记把相关的函数归集到相应的模块下面,这样你的整体的框架不至于过于零散和混乱。

@modulegroup label 使用范围:module 定义归属的模块组 label是这个模块组的名字,如果你的应用程序的模块很多,你可以把不同的模块按照逻辑功能的不同,划分成相应的模块组,这样,你的应用框架可以有比较清晰的逻辑关系。这是对于没有使用OOP编程的来说的,如果使用OOP的思想,没有必要使用模块组的概念,因为直接使用"包-超类--基类--子类"的形式来体现你的框架结构要比使用"包-模块组-模块"的形式好的多。

@package label 使用范围:class, module 定义归属的包的信息,label 是这个包的名字。相同的包的名字的类在最终文档索引中将被分在一起。实际上,包还可以理解为不同的名字空间,虽然PHP没有名字空间的概念,但是你可以把相关的类、模块都归属于同一个包,这样,相当于组织了一个名字空间,当然,你的应用框架可能会有不同的包,可惜的是,这种情况下从语法上是得不到名字空间这种保证的,你只能通过人为地去避免不同的包的函数或者类重名。

@param[eter] (object objecttype|type) [$varname] [description] 使用范围:function 定义函数或者方法的参数信息。这是最常使用的文档标记了。

ojecttype 是对象的类名,type 指出这个参数的类型,它可以是下列类型:

string 该参数是一个字符型变量。 array 该参数是一个数组。 integer 该参数是一个数值型。 integer (octal) 该参数是一个数值型,并且是按照八进制方式存放。 integer (hexadecimal) 该参数是一个数值型,并且是按照十六进制方式存放。 boolean 该参数是一个布尔型。 mixed 该参数的类型是可变的,可以上面几种类型的组合。不过,在随后的说明中一般要说明可以接受的变量的类型。 $varname 是形参的名称 [description] 是对于参数的说明。 如果函数接受的是多个参数,那么要按照从左到右,依次用@param对齐列出,如下面所示: ** @param array $tags array of tags returned by getTags* @param array $data array where the allowed tags and their values are copied to* @param array $allowed array of allowed (recognized) tags

@return (object objecttype|type) [$varname] 使用范围:function 定义函数或者方法的返回信息。 返回信息的类型同@param一样,$varname是返回变量的名称,可有可无。不同的是@return只有一个,不会出现多个@return

@see (function()|$varname|((module|class)::)(function()|$varname)) [, ...] 使用范围:class, function, var, module, define, use 定义需要参考的函数、变量,并加入相应的超级连接。这也是较常用的标记。对于相关的函数,变量,你可以使用@see来增加一个到相关函数和变量的链接。多个相关的函数、变量写在一行,中间用逗号来分隔。 参考的函数、变量如果是当前类或模块的,那么你可以直接写函数、或者变量的名,如果是函数那么要在函数名后面加上括号(),变量名要加上$。需要注意的,这里所谓的变量名也应该是你用@var来说明过的,否则,phpDocumentor将无法找到相关的参照而报错。 如果你想引用其他类或者其他模块的函数或者是变量,那么,你可以在函数名、变量名前面加上类或模块的名字作为范围指示,中间用::来分隔。

下面是一些例子: @see $run_time,$idle_time,$begin_time,$end_time @see getRuntime(), getIdletime(),getBegintime(),getEndtime() @see TIME::$run_time, TIME::getBegintime()

@since label 使用范围: class, function, var, module, define, use 指明该api函数或者方法是从哪个版本开始引入的。

@static 使用范围:class, function, var 指明变量、类、函数是静态的。

@throws exception [, exception] 使用范围: function 指明此函数可能抛出的错误异常,极其发生的情况 如果你预料到在这个函数中有产生异常的条件,那么你可以使用@throws标记来说明这些异常是什么,什么情况下产生异常。比如,读取磁盘文件出错,无法连接数据库,网络连接超时或者是在一些情况下,你"故意"抛出的异常等等。

@todo 使用范围:class, function, module, use 指明应该改进或没有实现的地方

@var[iable] (object objecttype|type) [$varname] [description] 使用范围:var 定义说明变量/属性。 object objecttype|type 定义你的变量的类型,同@param一样 $varname 该变量的名字,你可以从其他地方使用@see来引用这个名字 description 对变量的描述

@version label 使用范围:class, function, module, use 定义版本信息. 你当然可以自己手工写这些版本信息,不过PEAR推荐你使用CVS的$Id标记来自动标示你的版本信息。形式如下:

@version $Id 这样,当你checkout的时候,CVS自动会扩展成: @version $Id: PhpDocumentorParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp

PhpDocumentor标记的基本元素名为DocBlock,即一个多行注解块,它可以出现在任何PHP construct,类,或者函数之前,如下所示:

/** * text here* */

在这一DocBlock之中,PhpDocumentor接收三种类型的选项:一个简短描述,一个比较长的描述,以及一系列以@符号前缀的特定标签。这些标签为可选择性,然而它能够使最终文档变得更加精确。

当你开始这类自动文档系统使用时,我希望这篇文章能够给你带来帮助。但这只是冰山之一角,你还可以将PhpDocumentor应用到其它很多地方,你可以在excellent online tutorial(最为出色的在线使用指南)得到所有的信息。我希望你能够充分地利用PhpDocumentor的强大功能,在以后的PHP程序中节省时间和减轻压力。


最新回复(0)