PHP标准注释

Wednesday. April 03, 2019 - 2 mins

PHP

注释

PHPDOC说明地址： https://docs.phpdoc.org/

@name 名字
@abstract 申明变量/类/方法
@access 指明这个变量、类、函数/方法的存取权限
@author 函数作者的名字和邮箱地址

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

例如@author mokeyjay i@mokeyjay.com

@category 组织packages

@copyright 指明版权信息

格式@copyright [描述]

例如@copyright 1949-2016 China

@const 指明常量
@deprecate 指明不推荐或者是废弃的信息

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

例如@deprecated 1.0.0 新版本将不再包含此函数

如果它是被其他方法所取代了，建议添加@see标记

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

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

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

@exclude 指明当前的注释将不进行分析，不出现在文挡中
@final 指明这是一个最终的类、方法、属性，禁止派生、修改。
@global 指明在此函数中引用的全局变量

格式@global [类型][名称][描述]

类型@global string name 用户名

@ignore 忽略

格式@ignore [<描述>]
例如你在if和else的语句块中定义分别同一个变量但值不同时，可以通过此标记让phpDocumentor忽略其中一个，以免生成重复的文档。例如
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

@include 指明包含的文件的信息
@link 定义在线连接可用于辅助说明、引用文档等

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

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

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

格式@method [返回值类型] [名称] ( [ [类型] [参数]<, …> ] ) [<描述>]

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

@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 用户名

@module 定义归属的模块信息
@modulegroup 定义归属的模块组
@package 定义归属的包的信息
@param 定义函数或者方法的参数信息

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

例如@param string title 文章标题

@return 定义函数或者方法的返回信息
@see 定义需要参考的函数、变量，并加入相应的超级连接。类似@link，可与@deprecated联动

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

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

@since 指明该api函数或者方法是从哪个版本开始引入的

例如从1.0之后添加了xx功能、删除了xx参数等

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

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

@static 指明变量、类、函数是静态的。
@throws 指明此函数可能抛出的错误异常,极其发生的情况

可能会抛出的错误类型

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

例如@throws LifeException 没钱了，好想死啊

@todo 指明应该改进或没有实现的地方
@var 定义说明变量/属性, 可以设置类型帮助ide找到方法声明位置

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

例如@var int id 用户id

@version 定义版本信息

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

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

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

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

由于本人水平有限，文章在表述和代码方面如有不妥之处，欢迎批评指正。

PHP标准注释

注释

Related Posts