PHP之文档注释规范PHPDoc
良好的文档注释不但能使代码易于维护，而且可以通过phpDocumentor等文档生成工具生成项目手册，以便于查阅。此外PHP的弱类型特征更应该引起我们对文档注释的重视！本文简单的介绍下PHPDoc文档注释，以及常用的一些标签。
1. 文档注释并不只是用来注释整个文件的，在元素前面声明之后，它可以和该特定的程序元素相关联，例如类、函数、常量、变量、方法等等，以/**开头、*/结束，注意注释与相关联的程序元素间不能有空行；
2. 常用的标签
@authorAuthor Name [<author@email.com>] 代码编写人(负责人)
@version xx.xx 当前版本号
@param datatype $v_name[,...] description 函数相关联的参数，含有,...表示可传入不定数量的其他参数
@returndatatype description 函数或方法的返回值类型
@globaldatatype description 全局变量的说明(仅对phpDocumentor解析器起作用)
@var datatype 在类中说明类变量(属性)的类型
@example 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
* @copyrightCopyright (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
* @copyrightCopyright (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
*
* @paramarray|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');
}
}
//后面略...
页:
[1]