php注释要求

PHPDoc 注释要求

PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档，也可以帮助一些，例如Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之类的集成开发环境理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。

PHPDoc 可同时支持面向对象和面向过程的代码。以上摘自维基百科

简单来说PHPDOC可以用来自动生成API文档。主流的IDE都会识别它，并在你coding中给予你相应的智能提示。使用PHPDOC有以下好处

让你的代码更加规zhuang范bi，更易于理解
让你的IDE更懂你的代码，更加智能的提示和自动完成
如需API手册，可使用phpDocumentor来自动生成

@api

表示这是一个提供给第三方使用的API接口

@author

作者

格式 @author [名称] [<邮箱>]

例如 @author mokeyjay i@mokeyjay.com

@copyright

@deprecated

不建议使用的、已过期的、将被删除的

格式 @deprecated [<版本号>] [<描述>]

例如 @deprecated 1.0.0 新版本将不再包含此函数如果它是被其他方法所取代了，建议添加@see标记

@example

例子、示例、用例。也可表示方法返回值的例子

格式 @example [位置] [<起始行号> [<行数>] ] [<描述>]

例如 @example demo.php 10 3 使用示例

@filesource

没看懂，如果你们看懂了请告诉我。

@global

全局变量

格式 @global [类型][名称] @global [类型][描述] 我怀疑这里是源文档打错了，大概应该是

格式 @global [类型][名称][描述] 类型@global string name 用户名

@ignore

忽略

格式 @ignore [<描述>]

例如你在if和else的语句块中定义分别同一个变量但值不同时，可以通过此标记让phpDocumentor忽略其中一个，以免生成重复的文档。

例如

1
2
3
4
5
6
7
8
9
10
11
if ($ostest) {
     /**
      * This define will either be 'Unix' or 'Windows'
      */
     define("OS","Unix");
 } else {
     /**
      * @ignore
      */
     define("OS","Windows");
 }

@internal

仅限内部使用的

格式 @internal [描述]

例如 @internal 仅限内部测试使用

@license

协议，很常见的

格式 @license [] [名称]

例如 @license GPL

@link

链接，可用于辅助说明、引用文档等

格式 @link [url] [<描述>]

例如 @link http://g.cn 不懂滚去问谷歌，别来烦我

@method

方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE无法自动提示出来，这时就可以通过写@method标记来告诉IDE我这类里有哪些方法

格式 @method [返回值类型] 名称 [<描述>]

例如 @method string google(string $question) 向谷歌提问，返回答案内容

@package

包。但php没有包，所以就用来表示命名空间

例如 @package yii\base\db

@param

参数，用于函数和方法注释里的标记

格式 @param [Type] [name] []

例如 @param string title 文章标题

@property

类属性，与@method类似，可以告诉IDE我这类里有哪些属性

格式 @property [Type] [name] []

例如 @property int id 用户id

@property-read

只读的属性。例如__get魔术方法能够取到的属性

格式 @property-read [Type] [name] []

例如 @property-read int id 用户id

@property-write

只可写的属性。例如__set魔术方法能够设置的属性

格式 @property-write [Type] [name] []

例如 @property-write string name 用户名

@return

返回值

格式 @return [类型] [<描述>]]

例如 @return array 结果数组

@see

参考，类似@link，可与@deprecated联动

格式 @see [url或完整方法名] [<描述>]

例如 @see \yii\base\db::tableName() 旧方法table_name已弃用，请使用此方法替代

@since

从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等

格式 @since [1.0.0] [<描述>]

例如 @since 1.0.2 添加了$b参数

@source

没看懂

@throws

可能会抛出的错误类型

格式 @throws [类型] [<描述>]

例如 @throws LifeException

@todo

待办。提示自己或他人还需要做些什么

格式 @todo [描述]

例如 @todo 这个类还没做异常处理

@uses

使用

格式 @uses [完整方法名] [<描述>]

例如 @uses \yii\base\db::$count 使用此属性计数

@var

变量

格式 @var [类型] [变量名] [<描述>]

例如 @var int id 用户id

@version

版本号

格式 @version [<载体>] [<描述>]

例如 @version 1.0.1 2016-07-03更新

或者 @version GIT:1f3197d01 来自GIT分支1f3197d01