【小结】PHP之文档注释规范PHPDoc

良好的文档注释不但能使代码易于维护，而且可以通过phpDocumentor等文档生成工具生成项目手册，以便于查阅。此外PHP的弱类型特征更应该引起我们对文档注释的重视！

本文简单的介绍下PHPDoc文档注释，以及常用的一些标签。

1. 文档注释并不只是用来注释整个文件的，在元素前面声明之后，它可以和该特定的程序元素相关联，例如类、函数、常量、变量、方法等等，以/**开头、*/结束，注意注释与相关联的程序元素间不能有空行；

2. 常用的标签

@author  Author Name [<[email protected]>]      代码编写人(负责人)
@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'); } } //后面略...