你会写凝视么？从我写代码開始。这个问题就一直困扰着我。相信也相同困扰着其它同学。曾经的写凝视总是没有一套行之有效的标准，给维护和协同开发带了很多麻烦，直到近期读到了phpdocumentor的凝视标准。
以下对phpdocumentor的凝视标准进行总结：
Type（数据类型）:
- 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 自身
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 <my.name@example.com>
*/
// =============================
@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