每个 PHPer 都应当掌握的注释标记

前言

注释标签在代码注释中的作用非常大，好的找注释标签可以让你在编程过程中有更好、更舒适的体验，所以我今天准备整理一下这些标记，通过图文的形式展示出来，一方面是为了自己对这些注释标签有一个汇总整理，另一方面也希望大家能够更好对理解注释标签

每个人都希望写出漂亮的代码，或许你离漂亮的代码，就差一个标签

常用标签

标记	用途	描述
@abstract		抽象类的变量和方法
@access	public, private or protected	文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author	张三 zhangsan@163.com	文档作者
@copyright	名称时间	文档版权信息
@deprecated	version	文档中被废除的方法
@deprec		同 @deprecated
@example	/path/to/example	文档的外部保存的示例文件的位置。
@exception		文档中方法抛出的异常，也可参照 @throws.
@global	类型：$globalvarname	文档中的全局变量及有关的方法和函数
@ignore		忽略文档中指定的关键字
@internal		开发团队内部信息
@link	URL	类似于license 但还可以通过link找到文档中的更多个详细的信息
@name	变量别名	为某个变量指定别名
@magic		phpdoc.de compatibility
@package	封装包的名称	一组相关类、函数封装的包名称
@param	如 $username 用户名	变量含义注释
@return	如返回bool	函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see	如 Class Login()	文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since	version	记录什么时候对文档的哪些部分进行了更改
@static		记录静态类、方法
@staticvar		在类、函数中使用的静态变量
@subpackage		子版本
@throws		某一方法抛出的异常
@todo		表示文件未完成或者要完善的地方
@var	type	文档中的变量及其类型
@version		文档、类、函数的版本信息

上面这么多其实很大一部分都是创建文件、创建类的时候需要添加的。今天主要讲解一下常用的标签。

@param

说明

参数，用于函数和方法注释里的标记\
格式@param [Type] [name] [<description>]\
例如@param string title 文章标题

代码举例

每个PHPer都应当掌握的注释标记

@return

说明

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

代码举例

每个PHPer都应当掌握的注释标记

@deprecated

说明

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

代码举例

每个PHPer都应当掌握的注释标记

@see

说明

参考，类似@link，可与@deprecated联动
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tableName() 旧方法table_name已弃用，请使用此方法替代

代码举例

每个PHPer都应当掌握的注释标记

@link

说明

链接，可用于辅助说明、引用文档等\
格式@link [url] [<描述>]\
例如@link http://g.cn 不懂滚去问谷歌，别来烦我

代码举例

每个PHPer都应当掌握的注释标记

@link&@see区别

-	@see	@link
外部链接	√	√
内部程序	√	X

@var

说明

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

变量列表

变量类型	说明
string	字符串
integer/int	number/int类型
boolean/bool	false/true
float/double	number/浮点数
object	对象实例
specifiedType	指定类
mixed	任意类型
array/specifiedType[]	数组，可以指定成指定类型的数组
resource	文件资源类型
void	无返回值
null	-
callable	可执行的回调函数
function	不一定能执行的方法
self/$this	当前实例

代码举例

1、在方法外的变量定义
每个PHPer都应当掌握的注释标记
2、在方法内的变量定义

每个PHPer都应当掌握的注释标记

@throws

说明

可能会抛出的错误类型\
格式@throws [类型] [<描述>]\
例如@throws Exception

每个PHPer都应当掌握的注释标记

php 注释

本作品采用《CC 协议》，转载必须注明作者和本文链接

原创不易，转载请注明出处

本帖由系统于 6年前自动加精

讨论数量: 8

panda-sir

96 声望 / 后端开发工程师 @ 摸鱼协会

:+1:很实用

6年前评论

北行

课程读者 123 声望 / php @ 滴滴

@panda-sir 哈哈感谢大兄弟的肯定

hldh214

78 声望

Note that the @param attribute is followed by two spaces

https://learnku.com/docs/laravel/master/contributi...

挺好奇为啥要这样

@hldh214 其实可以归为三大类。

1、为了自己写代码的的时候不会去犯方法穿接值的错误

2、项目组里别的成员用你的方法时的出错的几率

3、看到文件就知道是谁写，谁维护的，这样到时候如果线上出问题了也方便排查

醉丶春风

2 声望

很实用, mark

一个人的江湖

Laravel 8.x 译者 345 声望 / 开发 @ 一个人的江湖

nice

GeorgeKing

L5.7 译者 762 声望

请教一下，如果方法的参数数量是不定的，比如下面的方法：

public function is()
{
    foreach (func_get_args() as $pattern) {
        if (Str::is($pattern, $this->decodedPath())) {
            return true;
        }
    }

    return false;
}

应该如何写参数的注释？

5年前评论

@GeorgeKing 这种情况我一般都是注释这个函数的作用，声明返回结果

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容，与人为善，比聪明更重要！

帮助

每个 PHPer 都应当掌握的注释标记

前言

常用标签

@param

说明

代码举例

@return

说明

代码举例

@deprecated

说明

代码举例

@see

说明

代码举例

@link

说明

代码举例

@link&@see区别

@var

说明

变量列表

代码举例

@throws

说明