PHPDocumentor 注释规范整理
- string 字符串类型
- integer or int 整型
- boolean or bool 布尔类型 true or false
- float or double 浮点类型
- object 对象
- mixed 混合类型 没有指定类型或不确定类型时使用
- array 数组
- resource 资源类型 (如数据库查询返回)
- void 空值(控制器返回值经常使用)
- null null类型
- callable 回调函数
- false or true 只返回true or fasle 时使用
- self 自身
你会写注释么?从我写代码开始,这个问题就一直困扰着我,相信也同样困扰着其他同学。以前的写注释总是没有一套行之有效的标准,给维护和协同开发带了许多麻烦,直到最近读到了phpdocumentor的注释标准。
下面对phpdocumentor的注释标准进行总结:
Type(数据类型):
Tags(标签):
Tag |
Element |
Description |
api |
Methods |
声明接口 |
author |
Any |
作者信息 |
category |
File, Class |
将一系列的元素分类在一起 |
copyright |
Any |
版权信息 |
deprecated |
Any |
声明元素已被弃用,可以在将来的版本中删除 |
example |
Any |
示例 |
filesource |
File |
文件资源 |
global |
Variable |
声明一个全集变量 |
ignore |
Any |
忽略当前元素 (phpdocumentor 生成文档时) |
internal |
Any |
声明一个值为整形,或者设置一个应用的默认值为整型 |
license |
File, Class |
声明许可类型 |
link |
Any |
声明一个和当前元素有关的链接 |
method |
Class |
声明当前类那些魔术方法可以被调用 |
package |
File, Class |
声明当前元素所属的包 |
param |
Method, Function |
声明当前元素的一个参数 |
property |
Class |
声明当前类有那些魔术方法可以被调用属性 |
property-read |
Class |
声明当前类有那些魔术方法可以读取属性 |
property-write |
Class |
声明当前类有那些魔术方法可以设置属性 |
return |
Method, Function |
返回值 |
see |
Any |
说明当前元素参数引用于其他站点或元素 |
since |
Any |
声明当前元素始于于哪个版本 |
source |
Any, except File |
展示当前元素的源码 |
subpackage |
File, Class |
将当期元素分类 |
throws |
Method, Function |
说明当前元素抛出的异常 |
todo |
Any |
说明当前元素的开发活动 |
uses |
Any |
引用一个关联元素 |
var |
Properties |
声明属性 |
version |
Any |
版本 |
Example(示例):
// =============================
@api
/** * This method will not change until a major release. * * @api * * @return void */ function showVersion() { <...> }
// =============================
@author
/** * @author My Name * @author My Name <[email protected]> */
// =============================
@category
/** * Page-Level DocBlock * * @category MyCategory * @package MyPackage */
// =============================
@copyright
/** * @copyright 1997-2005 The PHP Group */
// =============================
@deprecated
/** * @deprecated * @deprecated 1.0.0 * @deprecated No longer used by internal code and not recommended. * @deprecated 1.0.0 No longer used by internal code and not recommended. */ function count() { <...> }
// =============================
@example
/** * @example example1.php Counting in action. * @example http://example.com/example2.phps Counting in action by a 3rd party. * @example "My Own Example.php" My counting. */ function count() { <...> }
// =============================
@filesource
/** * @filesource */
// =============================
@global phpdocumentor2.0不支持
// =============================
@ignore
if ($ostest) { /** * This define will either be 'Unix' or 'Windows' */ define("OS","Unix"); } else { /** * @ignore */ define("OS","Windows"); }
// =============================
@internal
/** * @internal * * @return integer Indicates the number of items. */ function count() { <...> }
/** * Counts the number of Foo. * * {@internal Silently adds one extra Foo to compensate for lack of Foo }} * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@license
/** * @license GPL * @license http://opensource.org/licenses/gpl-license.php GNU Public License */
// =============================
@link
/** * @link http://example.com/my/bar Documentation of Foo. * * @return integer Indicates the number of items. */ function count() { <...> }
/** * This method counts the occurrences of Foo. * * When no more Foo ({@link http://example.com/my/bar}) are given this * function will add one as there must always be one Foo. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@method
class Parent { public function __call() { <...> } } /** * @method string getString() * @method void setInteger(integer $integer) * @method setString(integer $integer) */ class Child extends Parent { <...> }
// =============================
@package
/** * @package PSR\Documentation\API */
// =============================
@param
/** * Counts the number of items in the provided array. * * @param mixed[] $items Array structure to count the elements of. * * @return int Returns the number of elements. */ function count(array $items) { <...> }
// =============================
@property
class Parent { public function __get() { <...> } } /** * @property string $myProperty */ class Child extends Parent { <...> }
// =============================
@property-read
class Parent { public function __get() { <...> } } /** * @property-read string $myProperty */ class Child extends Parent { <...> }
// =============================
@property-write
class Parent { public function __set() { <...> } } /** * @property-write string $myProperty */ class Child extends Parent { <...> }
// =============================
@return
/** * @return integer Indicates the number of items. */ function count() { <...> }
/** * @return string|null The label's text or null if none provided. */ function getLabel() { <...> }
// =============================
@see
/** * @see http://example.com/my/bar Documentation of Foo. * @see MyClass::$items for the property whose items are counted * @see MyClass::setItems() to set the items for this collection. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@since
/** * @since 1.0.1 First time this was introduced. * * @return integer Indicates the number of items. */ function count() { <...> }
/** * @since 1.0.2 Added the $b argument. * @since 1.0.1 Added the $a argument. * @since 1.0.0 * * @return void */ function dump($a, $b) { <...> }
// =============================
@source
/** * @source 2 1 Check that ensures lazy counting. */ function count() { if (null === $this->count) { <...> } }
// =============================
@subpackage
/** * @package PSR * @subpackage Documentation\API */
// =============================
@throws
/** * Counts the number of items in the provided array. * * @param mixed[] $array Array structure to count the elements of. * * @throws InvalidArgumentException if the provided argument is not of type * 'array'. * * @return int Returns the number of elements. */ function count($items) { <...> }
// =============================
@todo
/** * Counts the number of items in the provided array. * * @todo add an array parameter to count * * @return int Returns the number of elements. */ function count() { <...> }
// =============================
@uses
/** * @uses MyClass::$items to retrieve the count from. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@var
class Counter { /** * @var */ public $var; }
// =============================
@version
/** * @version 1.0.1 */ class Counter { <...> }
/** * @version GIT: $Id$ In development. Very unstable. */ class NeoCounter { <...> }
// =============================
phpdocumentor手册:http://www.phpdoc.org/docs/latest/index.html
(本人英语水平有限,如果翻译不当,请提出,定当及时修正)
郑重声明:本站内容如果来自互联网及其他传播媒体,其版权均属原媒体及文章作者所有。转载目的在于传递更多信息及用于网络分享,并不代表本站赞同其观点和对其真实性负责,也不构成任何其他建议。