PHP之文档注释规范PHPDoc

bco

良好的文档注释不但能使代码易于维护，而且可以通过phpDocumentor等文档生成工具生成项目手册，以便于查阅。此外PHP的弱类型特征更应该引起我们对文档注释的重视！
本文简单的介绍下PHPDoc文档注释，以及常用的一些标签。
1. 文档注释并不只是用来注释整个文件的，在元素前面声明之后，它可以和该特定的程序元素相关联，例如类、函数、常量、变量、方法等等，以/**开头、*/结束，注意注释与相关联的程序元素间不能有空行；
2. 常用的标签
@author  Author Name [<author@email.com>]      代码编写人(负责人)
@version xx.xx                                 当前版本号
@param   datatype $v_name[,...] description    函数相关联的参数，含有,...表示可传入不定数量的其他参数
@return  datatype description                  函数或方法的返回值类型
@global  datatype description                  全局变量的说明(仅对phpDocumentor解析器起作用)
@var     datatype                              在类中说明类变量(属性)的类型
@example [path|url] description                举一个例子，以阐释使用方法
@todo    description                           待完成的工作信息或待解决的问题信息
更多的标签请参考 http://en.wikipedia.org/wiki/Phpdoc
这里举一个Zend Framework里的一段代码为例：

<?php  
/**
* Zend Framework
*
* LICENSE
*
* This source file is ...
*
* @category   Zend
* @package    Zend_Db
* @subpackage Adapter
* @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
* @license    http://framework.zend.com/license/new-bsd     New BSD License
* @version    $Id: Abstract.php 19115 2009-11-20 17:41:25Z matthew $
*/  

/**
* @see Zend_Db
*/  
require_once 'Zend/Db.php';  
/**
* Class for connecting to SQL databases and performing common operations.
*
* @category   Zend
* @package    Zend_Db
* @subpackage Adapter
* @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
* @license    http://framework.zend.com/license/new-bsd     New BSD License
*/  
abstract class Zend_Db_Adapter_Abstract  
{  
/**
* User-provided configuration
*
* @var array
*/  
protected $_config = array();  
/**
* Constructor.
*
* $config is an array of key/value pairs or an instance of Zend_Config
* containing configuration options.  These options are common to most adapters:
*
* dbname         => (string) The name of the database to user
* username       => (string) Connect to the database as this username.
* password       => (string) Password associated with the username.
* host           => (string) What host to connect to, defaults to localhost
*
* Some options are used on a case-by-case basis by adapters:
*
* port           => (string) The port of the database
* persistent     => (boolean) Whether to use a persistent connection or not, defaults to false
* protocol       => (string) The network protocol, defaults to TCPIP
* caseFolding    => (int) style of case-alteration used for identifiers
*
* @param  array|Zend_Config $config An array or instance of Zend_Config having configuration data
* @throws Zend_Db_Adapter_Exception
*/  
public function __construct($config)  
{  
/*
* Verify that adapter parameters are in an array.
*/  
if (!is_array($config)) {  
/*
* Convert Zend_Config argument to a plain array.
*/  
if ($config instanceof Zend_Config) {  
$config = $config->toArray();  
} else {  
/**
* @see Zend_Db_Adapter_Exception
*/  
require_once 'Zend/Db/Adapter/Exception.php';  
throw new Zend_Db_Adapter_Exception('Adapter parameters must be in an array or a Zend_Config object');  
}  
}  
//后面略...