每个 PHPer 都应当掌握的注释标记(收录自LearnKu.com)

  1. 2 周前
    2

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

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

    常用标签
    标记 用途 描述
    @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都应当掌握的注释标记

或者 注册后参与话题.