<![CDATA[阿Tim日志]]> https://atim.cn/index.php zh-cn https://atim.cn/post/1018/ <![CDATA[phpdoc应用]]> bkkkd <partybase@gmail.com> Mon, 04 Jul 2011 10:23:48 +0000 https://atim.cn/post/1018/ PHPDoc 是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。
从这一点上讲， PHPdoc 促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
编制符合 PHPDoc 规范的注释是非常重要的，掌握了这一点，基本上就可以利用 PHPDo c 为你工作了。
注释在 PHPDoc 中分为文档注释和非文档注释
1. 文档注释
文档注释实际上是一些特殊形式的多行注释，一般是放在你需要注释的特定的关键字 ( 这些关键字是指将会被 phpdoc 分析的那些关键字，相关的关键字列表请参看后面第 4 节的说明）前面。下面是一个文档注释的例子：

<?php
/**
* Common base class of all phpdoc classes （简述，用在索引列表中）
*
* As a kind of common base class PhpdocObject holds
* configuration values (e.g. error handling) and debugging
* methods (e.g. introspection()). It does not have a constructor,
* so you can always inheritig Phpdoc classes from this
* class without any trouble. （详细的功能描述）
*
* @author Ulf Wendel
* @version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
* @package PHPDoc （文档标记）
*/
class PhpdocObject {
.....
}
?>

以上的文档注释将会生成如下的文档：

<b>PhpdocObject</b>
PhpdocObject
Common base class of all phpdoc classes
<b>private class PhpdocObject </b>
Common base class of all phpdoc classes
As a kind of common base class PhpdocObject holdsconfiguration values (e.g. error
handling) and debuggingmethods (e.g. introspection()). It does not have a
constructor,so you can always inheritig Phpdoc classes from thisclass without any trouble.
Authors Ulf Wendel <ulf.wendel@phpdoc.de>
Version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $

2. 非文档性注释
如果你的注释没有放在那些 phpdoc 指定的关键字前面，那么 phpdoc 认为你所作的这些注释是属于非文档注释，将不会被 phpdoc 所分析，也不会出现在你产生的 api 文当中。
3. 文档书写指南
首先，第一行是一个注释开始的标志 "/**" ，然后是回车，从第 2 行开始就是功能简述区，功能简述区是以缩进的 "*" 开始的，在简述的正文和这个 "*" 号之间用空格分隔（注意，在文档中，都是以 * 开始，并且这些 * 保持对齐的缩进格式）。功能简述的正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。
在文档标记区下面的一行就是注释结束行 "*/", 注意，在注释结束标记 */ 后面应该直接跟一个回车，不要另外附加其他的东西，否则可能造成 PHPDOC 分析出错。
在你描述你的代码的用途或者是功能的时候，最好能够遵循大多数人的习惯，通俗地讲就是 " 你告诉我的信息正是我想要知道的 " 。为此，这里将介绍一些书写文档注释的技巧和规范，希望能够对你有所帮助：
a) 使用 来标志关键字和命名及相关的代码。如果在文档中需要引用一些关键字，变量名，或者是你要给出一些代码的例子，那么你最好使用 来将这些关键字，变量名，代码片段和你的文档分隔开，这样，读者阅读的时候，将会知道，这些将是运行的代码，关键字而不是你的描述性的语言。
b) 使用简单，明确的语言，避免冗长，复杂，晦涩的长句来描述。尤其是在功能简述，参数说明等索引部分中，尽量使用简单明白的语言揭示主要的信息，把其他的细节放在详细说明部分去阐述。如果你使用英语，建议使用短语而不一定是句子。
c) 如果使用英语，建议使用第 3 人称单数的形式来说明
d) 在给方法，函数说明的时候，你需要说明的是这个方法 " 作了什么 " ，而不是 " 怎么做 " 。因此，建议你的说明是以动词开始，比如 " 返回记录数 " ， " 删除给定的记录 " 等等。
e) 当你引用的某个对象或者变量是从当前的类中建立的，那么使用 "this" 代替 "the" 来指代那个对象或者是变量
f) 避免空话，废话，对于你所要给出的 API ，在你的 API 后面要有它的功能描述，是其能够 " 自成文档 " 。所谓的空话，废话是指，你的描述不是功能描述，而只是 API 名称的简单重复和罗列，或者是用另一个 API 来解释这个 API ，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的 API 名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：

<?php
/**
* 设置用户记录集
*
* @param text 给定的表名
*/
function set_user_record($table) {}
?>

你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：

<?php
/**
* 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。如果失败则抛出一个数据库错误。
*
* @param text 要打开的系统用户表的表名。
*/
function set_user_record($table) {}
?>

------------------------------------------------------------------
文档标记说明
说明：使用范围是指该标记可以用来修饰的关键字，或其他文档标记
@abstract 使用范围： class, function, var
说明当前类是一个抽象类。
注释：从 PHP 语言角度来说，它并不象 JAVA ， C++ 那样，支持抽象类这个概念。也没有相应的关键字来修饰某个类是抽象类。由于 PHPDOC 实际上大部分是借鉴了 JAVADOC 的做法，因此很多文档标记也是直接从 JAVADOC 中沿袭过来，如 abstract,access,fi nal 等等。虽然这些特性没有从语言级别得到支持，不过从使用者角度来遵循这些特性，仍是值得推荐的。
举例：

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

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

<?php
/**
* 这是一个绘五星图案的抽象类 .
* @abstract
* @access public
*/
class paint_start {
/**
* 绘制数量
* @abstract
* @access private
*/
var $number;
/**
* 绘制五星图案
* @abstract
* @access public
*/
function paint() {
;
}
}
?>

@author Name [] [, ...] 使用范围： class, function, var, define, module, use
指明作者信息 , 依次是作者姓名， email 地址，其他的通讯信息。如果有多个作者，按照其先后次序，使用多个 @author 依次列出：
* @author Night Sailer
* @author Lee Tester
@brother (function()|$variable) 使用范围： class, function, var, define, module, use
@sister (function()|$variable) 使用范围： class, function, var, define, module, use
指出兄弟类、函数或者是变量 . 这些函数、类、变量等有相似的信息和并实现相同的功能。比如，调用和返回的参数的个数和类型相同，实现的功能也一样。这种情况，你可以使用 @brother 或者 @sister 指明它的兄弟函数，无须在重复书写函数的功能等信息了。
举例：

<?php
/**
* 这是一个绘五星图案的抽象类 .
* @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 http://www.phpdoc.de/ PHPDoc Home
@magic description
这个标记在 phpdoc 中没有说明，具体用法现在仍不清楚
@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 来说明过的，否则， phpdoc 将无法找到相关的参照而报错。
如果你想引用其他类或者其他模块的函数或者是变量，那么，你可以在函数名、变量名前面加上类或模块的名字作为范围指示，中间用：：来分隔。
下面是一些例子：
@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: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp
------------------------------------------------------------------------- -----------------------
我们的开发中增加注释需要注意的情况
1. 判断的注释

<?
if($data==1){/* 当 $data 为 1 时 , 将执行 yyy 操作 */
....
}elseif($data==2){/* 当 $data 为 2 时 , 将执行 xxx 操作 */
....}else{/* 上面的判断都不正确时 , 将会执行 zzz 操作 */
....
}
?>

2. 函数的注释

<?
/**
* 函数的作用 . 主要用途
* <code>
* $data = 1;
* $render = func($data);//$data
* </code>
* @param string $data 参数的描述
* @param integer $param 参数的描述
* @param array $config 参数的描述
* @return array $render 返回数据的描述
* @global integer $timestamp 全局的时间截
*/
function func($data,$param=1,$config=array()){
global $timestamp;
....
return $render;
}
?>

3, 类的定义 ( 包括 model 的定义 )

<?php
/**
* mia_company_indexes 的 model 类
* @package Model
* @access public
*/
class CompanyIndexesModel extends NModel {
/**
* 数据表的别名 , 一般情况下为 Model 的类名 (CompanyIndexesModel) 去掉后面的 Model
* @access public
*/
var $Name;
/**
* 入库检查日期的方法
* @access private
* @brother rc_date()
*/
function c_date($data) {
;
}
/**
* 出库时检查日期的方法
* @access private
* @brother c_date()
*/
function rc_date($data) {
;
}
}
?>

4, 常量的定义

<?php
/**
* 定义程序所在的目录所在的目录地址
* @const AP
*/
define('AP','/home/madeinasia/web/app');
?>
]]> https://atim.cn/post/1018/#blogcomment2750 <![CDATA[[评论] phpdoc应用]]> 站长查询 <user@domain.com> Sun, 17 Jul 2011 17:01:53 +0000 https://atim.cn/post/1018/#blogcomment2750