PHPDOC复习

为了解决phpstorm中在extract($params)后使用参数提示未定义问题，复习一下PHPDoc的使用。

先说解决方便，：

// 在使用方法或变量前声明一下变量
/** 
 * @var int $page 
 * @var int $size 
*/ 
extract($params);

接下来复习一下PHPDoc：

PHPDoc是一种用于编写PHP代码文档的标准，它使用特殊的注释语法来描述函数、类、变量等元素的用途、参数、返回值等信息。这些注释可以被解析器或文档生成工具自动提取并生成文档

常用的有： 

@var

变量
格式：@var [类型] [变量名] [<描述>]
例如：@var int id 用户id

@api

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

@author

作者
格式：@author [名称] [<邮箱>]
例如：@author mokeyjay <i@mokeyjay.com>

@deprecated

不建议使用的、已过期的、将被删除的
格式：@deprecated [<版本号>] [<描述>]
例如：@deprecated 1.0.0 新版本将不再包含此函数
如果它是被其他方法所取代了，建议添加@see标记

@example

例子、示例、用例。也可表示方法返回值的例子
格式：​​​​​​​@example [位置] [<起始行号> [<行数>] ] [<描述>]
例如：@example demo.php 10 3 使用示例

@global

全局变量
格式：​​​​​​​@global [类型][名称][描述]
类型：@global int id 用户id

@ignore

忽略
格式：@ignore [<描述>]

@internal

仅限内部使用的
格式：​​​​​​​@internal [描述]
例如：@internal 仅限测试使用

@license

协议
格式：​​​​​​​@license [<url>] [名称]
例如：@license http://XXXX  XXX协议

@link

链接，于辅助说明、引用文档等
格式：@link [url] [<描述>]
例如：@link http://XXXX 接口描述文档地址

@method

方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE无法自动提示出来，这时就可以通过写@method标记来告诉IDE这类里有哪些方法，laravel等框架中很多使用可以去看看。
格式：​​​​​​​@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
例如：@method static \Illuminate\Database\Query\Builder table(string $table)

@param

参数，用于函数和方法注释里的标记
格式：​​​​​​​@param [Type] [name] [<description>]
例如：@param int id 用户id

@return

返回值
格式：​​​​​​​​​​​​​​@return [类型] [<描述>]]
例如：​​​​​​​@return array 结果数组

@see

参考，类似@link，可与@deprecated联动
格式：​​​​​​​​​​​​​​@see [url或完整方法名] [<描述>]
例如：​​​​​​​@see newfun() 旧方法已弃用，请使用newfun()方法替代

@since

从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等
格式：​​​​​​​​​​​​​​@since [1.0.0] [<描述>]
例如：​​​​​​​@since 1.0.2 添加了$b参数

@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 XXXX修复版本