1. 文档块必须用 "/*" 或者 "/**" 作为开头。"#" 是不允许的，而 “//” 的使用仅限于函数内部。
例如 ：
* 类描述
*/
class foo
{
/* 变量描述 */
public $foo;
/**
* 函数描述
*/
public function __construct()
{
// 用 '//' 进行注释仅允许在函数内部
$this->foo = 'foo';
# 用 '#' 进行注释是不允许的
$this->foo = 'bar';
}
}
2. 一个文档块应当包含一个短描述以及最少一个描述参数 "@xxx" 。当然，一段较长的附加描述和多个描述参数都是允许且鼓励的。
例如 ：
* 至少一段短描述和一个描述参数
*
* @param
*/
/**
* 长描述以及多个描述参数
*
* 我们用空行分隔开
* 短描述,
* 长描述,
* 以及参数描述
*
* @param
* @todo
*/
3. 文档块中除了关键描述词之外，所有内容必须有相同的缩进。
例如 ：
* 正确
*
* @component 所有描述内容
* @uses 有相同的缩进
*/
/**
* 错误
*
* @component 所有描述内容
* @uses 并没有缩进排列
*/
4. 当描述变量信息时，例如关键词，变量名，变量描述，它们彼此间要保持缩进对齐。
例如 ：
* 正确, 所有描述都对齐
*
* @param string $value 变量描述
* @param integer $othervalue 另一变量的描述
*/
/**
* 错误, 没有对齐
*
* @param string $value 变量描述
* @param integer $othervalue 另一变量的描述
*/
5. 所有 Zend Framework 发行包里面的 php 文件都必须包含以下头文档块。
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend
* @package __PACKAGENAME__
* @subpackage __SUBPACKAGENAME__
* @copyright Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: $
* @depreciated Since 0.0.1
*/
实际上此格式适用于任何项目，例如 ：
/**
* 项目名称
*
* LICENSE
*
* 许可信息
* 通常包括多行内容
*
* @category 所属
* @package 所在包
* @subpackage 所在子包
* @copyright 版权信息
* @license 许可信息
* @version $ 版本信息 $
* @depreciated 关注程度
*/
6. 除非是遇到不支持文档块的文件类型，如 *.css 等，不然都必须在文档顶部加上描述块，这类文件包括 *.sh, *.bat, *.js 等等。
例如 ：
// zf.bat
REM
REM LICENSE
REM
REM This source file is subject to the new BSD license that is bundled
REM with this package in the file LICENSE.txt.
REM It is also available through the world-wide-web at this URL:
REM http://framework.zend.com/license/new-bsd
REM If you did not receive a copy of the license and are unable to
REM obtain it through the world-wide-web, please send an email
REM to license@zend.com so we can send you a copy immediately.
REM
REM Zend
REM Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
REM http://framework.zend.com/license/new-bsd New BSD License
// zf.sh
# Zend Framework
#
# LICENSE
#
# This source file is subject to the new BSD license that is bundled
# with this package in the file LICENSE.txt.
# It is also available through the world-wide-web at this URL:
# http://framework.zend.com/license/new-bsd
# If you did not receive a copy of the license and are unable to
# obtain it through the world-wide-web, please send an email
# to license@zend.com so we can send you a copy immediately.
#
# Zend
# Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
# http://framework.zend.com/license/new-bsd New BSD License
#############################################################################
// *.js
与 php 文件类似
7. 描述参数 @package 表示的是该文件所属的模块组件，每个文件的顶部都必须明确显示该文件所属的模块。
例如 ：
* ...
*
* @package Zend_Controller
* @subpackage ...
* @copyright ...
* @license ...
*/
abstract class Zend_Controller_Router_Route_Abstract implementsZend_Controller_Router_Route_Interface
{
// ...
}
又如 ：
* ...
*
* @package Zend_Db
* @subpackage ...
* @copyright ...
* @license ...
*/
class Zend_Db_Adapter_Mysqli extends Zend_Db_Adapter_Abstract
{
// ...
}
8. 描述参数 @subpackage 用于在逻辑上分割一个模块组件中的各个元素（通常指各个子文件夹）。仅当该文件直属顶级文件夹 "Zend" 时，@subpackage 可以被省略。文件块信息中最多仅包含一个 @subpackage 描述参数。
例如 ：
* @category ...
* @package ...
* @subpackage Adapter
* @copyright ...
* @license ...
*/
class Zend_Db_Adapter_Mysqli extends Zend_Db_Adapter_Abstract
{
// ...
}
又如 ：
* @category ...
* @package ...
* @subpackage Table
* @copyright ...
* @license ...
*/
class Zend_Db_Table_Select extends Zend_Db_Select
{
// ...
}
没有 subpackage 的例子 ：
* @category Zend
* @package Zend_Auth
* @copyright ...
* @license ...
*/
class Zend_Auth
{
// ...
}
9. 描述参数 @copyright 必须包括明确的发行年份。
例如 ：
* @category ...
* @package ...
* @copyright Copyright (c) 2005-2008 Zend ...
* @license ...
*/
class Zend_Acl
{
// ...
}
10. 如果文件中的类在未来可能不再受重视，或者将废弃，则必须为它加上 @depreciated 描述。
例如 ：
/**
* ...
*
* @depreciated Since 1.1.1
*/
class depreciateMe
{
}
11. 所有被加载的文件或类文件都必须含有 @see 描述。
例如 ：
* @see Zend_Controller_Dispatcher_Interface
*/
require_once 'Zend/Controller/Dispatcher/Interface.php';
12. Zend Framework 中的所有类或者接口文件都必须含有头文档块，且具体顺序必须按以下显示的加以罗列。
* Description of the class
*
* More descriptive text which
* is allowed to span multiple lines
*
* @category Zend
* @package __PACKAGE__
* @subpackage __SUBPACKAGE__
* @uses __USES__
* @see __SEE__
* @since __SINCE__
* @copyright Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @depreciated Since 0.0.1
*/
class Zend_Controller_Dispatcher extends Zend_Controller_Dispatcher_Class implementsZend_Controller_Dispatcher_Interface
13. 描述参数 @uses 是用于声明该类的父类或实现的借口。每个父类及接口对应一个 @uses 描述。当一个类本身并不存在继承关系或没有实现任何接口时，@uses 将被省略。
例如 ：
* ...
*
* @uses ArrayAccess
* @uses Iterator
* @uses Countable
* @package ...
* @copyright ...
* @license ...
*/
class Zend_Dojo_Data implements ArrayAccess,Iterator,Countable
{
// ...
}
14. 描述参数 @see 用于链接框架中的其它组件。
例如 ：
* ...
*
* @see Zend_Parent
* @see Zend_Interface
* @package ...
* @copyright ...
* @license ...
*/
class Zend_Class extends Zend_Parent implements Zend_Interface
{
// ...
}
15. 描述参数 @since 用来表示该类生效的版本信息，其中必须包括完整的版本号，且一个类文件只能有一个 @since 描述。
例如 ：
* ...
*
* @category ...
* @package ...
* @copyright ...
* @license ...
* @since Class available since Release 0.6.0
*
* @todo ...
*/
class Zend_Console_Getopt
{
// ...
}
16. 每个函数都必须有自己的头描述块。
例如 ：
{
/**
* 函数的完整描述。
* 描述应包括所有可能性，
* 但长度最好不超过100个字符。
*
* @param boolean $value 布尔值
* @since 版本 1.2.3
* @see Zend_Anything
* @throws Zend_Exception 当遇到 false 时
* @return array
*/
public function bar($value)
{
require_once('Zend/Anything.php');
if ($value) {
return array('foo' => $value);
} else {
throw new Zend_Exception('抛出异常!');
}
}
}
17. 所有函数参数都必须是符合标准的。所有允许的类型罗列如下 ：
(a) boolean
(b) integer
(c) string
(d) float
(e) array
(f) false
(g) true
(h) null
(i) Zend_Xxx (必须是存在的 Zend Framework 类)
18. 如果参数可能有多种可能类型，则类型之间用 "|" 号隔开。
例如 ：
* @param array|null $config configurations
*/
19. 如果某个参数是可以忽略的，那么必须用在参数描述前加上 (optional) 字样。
例如 ：
* @param array|null $config (optional) My optional value
*/
20. 必须用 @throws 描述函数中抛出的任何异常，多个异常间用 "|" 号分隔，且必须解释清楚为什么抛出该异常。
例如 ：
{
/**
* Handle an xmlrpc call (actual work)
*
* @param Zend_XmlRpc_Request $request
* @return Zend_XmlRpc_Response
* @throws Zend_XmlRpcServer_Exception|Exception
* Zend_XmlRpcServer_Exceptions are thrown for internal errors; otherwise,
* any other exception may be thrown by the callback
*/
protected function _handle(Zend_XmlRpc_Request $request)
{
// ...
}
}
21. 函数中必须总是用 @return 描述返回值，除非是构建函数和析构函数，则可以省略。各返回值间用 "|" 号分隔。返回值的描述不是必需的，但鼓励写上。
例如 ：
{
/**
* Overloading: access to elements, form groups, and display groups
*
* @param string $name
* @return Zend_Form_Element|Zend_Form|null
*/
public function __get($name)
{
// ...
}
}
22. 如果一个函数返回的是自身（即流畅接口），则对返回值的描述应当加上 "Provides a fluent interface".
例如 ：
{
/**
* Sets the persistent storage handler
*
* @param Zend_Auth_Storage_Interface $storage
* @return Zend_Auth Provides a fluent interface
*/
public function setStorage(Zend_Auth_Storage_Interface $storage)
{
$this->_storage = $storage;
return $this;
}
}
23. 如果一个函数没有返回，则返回值必须设为 "void".
例如 ：
{
/**
* Run the application
*
* @return void
*/
public function run()
{
$this->getBootstrap()->run();
}
}
24. 记住 "void" 和 "null" 是不一样的。"null" 意味着返回一个空的变量。而 "void" 则表示什么都没有返回。这个虽然是小问题，但却非常重要，所以即使代码中没有出现 return 语句，我们依然要声明返回值为 "void"。
例如 ：
{
/**
* @return void
*/
public function returnTheVoid()
{
// 没有东西返回
}
/**
* @return null
*/
public function returnTheNull()
{
return null;
}
}
