PHP之文档注释规范PHPDoc

良好的文档注释不但能使代码易于维护，而且可以通过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');  
                }  
            }  

            //后面略...