什么是注释标记

我们在平常写代码或看别人写的代码时, 在方法的说明注释中经常会有这样的注释:

/**
* @param $num
* @return array
*/

上面的@param @return 就是注释标记

注释标记用于生成文档, param指明需要接收的参数, return指明返回值

在使用 phpDocumentor 等工具生成文档时, 会识别相关注释, 而且IDE也会识别, 在编码的过程中会给出提示.

PHP注释标记总结

  • @api: 提供给第三方使用的接口
  • @author: 标明作者
  • @param: 参数
  • @return: 返回值
  • @todo: 待办
  • @version: 版本号
  • @inheritdoc: 文档继承
  • @property: 类属性
  • @property-read: 只读属性
  • @property-write: 只写属性
  • @const: 常量
  • @deprecated: 过期方法
  • @example: 示例
  • @final: 标识类是终态, 禁止派生
  • @global: 指明引用的全局变量
  • @static: 标识类、方法、属性是静态的
  • @ignore: 忽略
  • @internal: 限内部使用
  • @license: 协议
  • @link: 链接,引用文档等
  • @see: 与 link 类似, 可以访问内部方法或类
  • @method: 方法
  • @package: 命名空间
  • @since: 从指定版本开始的变动
  • @throws: 抛出异常
  • @uses: 使用
  • @var: 变量
  • @copyright: 版权声明

@author

标明作者

/*
* @author hujing <hu@163.com>
* hujing: 作者名
* hu@163.com: 邮箱
*/

@copyright

版权声明

@copyright [描述]

@deprecated

标明方法是不建议使用的、已过期的或将要删除的

/*
* 语法:
* @deprecated [版本号] [描述]
* eg:
* @see Class::test()
* @deprecated 2.0 将被弃用,请使用test方法
*/

@inheritdoc

会继承父类文档, 且子类出现冲突文档时重写父类文档

@internal

标识此类或方法仅限当前文件使用

@description [描述]

@link

指明外部链接, 必须给出完整url

@link [url] [描述]

@see

此链接不光可以跳转到外部链接, 还可以跳转到内部的指定方法等, 如: class::method

@see [url|内部方法] [描述]

@var

定义数据的类型

@var [类型] [变量名] [描述]

/**
* 可以指定变量的类型
* @var array 名称列表
* 也可以指定变量名, 指定变量时数组或空
* @var array|null $nameList 名称列表
*/

类型列表如下:

  • string: 字符串
  • int/integer: 数字
  • boolean/bool: 布尔
  • float/double: 浮点
  • object: 对象实例
  • TestClass: 指定类
  • mixed: 任意类型
  • array: 数组
  • TestClass[]: 指定类型数组
  • resource: 文件资源
  • void: 无
  • null:
  • callable: 回调函数
  • function: 方法
  • self/$this: 当前实例

@throws

抛出异常

@throws [类型] [描述]

@method

类注释, 标明该类可以调用的方法, 可以令IDE自动提示等

/**
* @method string test(int num) 测试方法
*/

@param

标识参数信息, 类型可参考 @var

@param [类型] [名称] [描述]

@property

类属性, 指明可以直接访问与修改的类属性, 私有属性需要通过 __get __set 魔术方法设置与访问, 类型参考 @var

@property [类型] [名称] [描述]

@property-read

类属性, 指明只读的类属性, 私有属性需要通过 __get 魔术方法访问, 类型参考 @var

@property-write

类属性, 指明只写的类属性, 私有属性需要通过 __set 魔术方法设置, 类型参考 @var

@return

标识方法的返回值, 类型参考 @var

@return [类型] [描述]

@global

标明用到的全局变量

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

@ignore

标明生成文档是忽略的值

@users

标明使用到了哪些值

/**
* @users Class::$num 使用此属性计数
*/

有一些注释没有给出说明, 是因为个人不是常用, 当然还有一些注释没有总结到, 后面用到了再总结.

PHP注释标记整理的更多相关文章

  1. PHP压缩html网页代码原理(清除空格,换行符,制表符,注释标记)

    本博启用了一个叫wp super cache的页面压缩工具, 源代码没有去查看,不过原理很简单. 我们可以自己动手书写一个压缩脚本. 清除换行符,清除制表符,去掉注释标记 .它所起到的作用不可小视. ...

  2. JVM内存管理------GC算法精解(复制算法与标记/整理算法)

    本次LZ和各位分享GC最后两种算法,复制算法以及标记/整理算法.上一章在讲解标记/清除算法时已经提到过,这两种算法都是在此基础上演化而来的,究竟这两种算法优化了之前标记/清除算法的哪些问题呢? 复制算 ...

  3. PHP Document 注释标记及规范 && PHP命名规范

    注释标记 @access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指 ...

  4. <转>GC其他:引用标记-清除、复制、标记-整理的说明

    注:本文根据<深入理解Java虚拟机>第3章部分内容整理而成. 对象死亡历程 1.基本的mark&sweep是必须的,后续的都是对他的改进, 2.young代理的survivor就 ...

  5. JVM垃圾收集算法(标记-清除、复制、标记-整理)

     [JVM垃圾收集算法] 1)标记-清除算法: 标记阶段:先通过根节点,标记所有从根节点开始的对象,未被标记的为垃圾对象(错了吧?) 清除阶段:清除所有未被标记的对象 2)复制算法: 将原有的内存空间 ...

  6. GC其他:引用标记-清除、复制、标记-整理的说明

    对象死亡历程 1.基本的mark&sweep是必须的,后续的都是对他的改进, 2.young代理的survivor就是使用了复制算法,避免碎片 3.还有标记整理算法(压缩),就是将存活的对象移 ...

  7. JVM之GC算法、垃圾收集算法——标记-清除算法、复制算法、标记-整理算法、分代收集算法

    标记-清除算法 此垃圾收集算法分为“标记”和“清除”两个阶段: 首先标记出所有需要回收的对象,在标记完成后统一回收所有被标记对象,它的标记过程前面已经说过——如何判断对象是否存活/死去 死去的对象就会 ...

  8. JVM内存管理之GC算法精解(复制算法与标记/整理算法)

    本次LZ和各位分享GC最后两种算法,复制算法以及标记/整理算法.上一章在讲解标记/清除算法时已经提到过,这两种算法都是在此基础上演化而来的,究竟这两种算法优化了之前标记/清除算法的哪些问题呢? 复制算 ...

  9. C#中的XML文档注释-推荐的文档注释标记

    文档注释是为了方便自己和他人更好地理解代码所实现的功能.下面记录了一些常用的文档注释标记: <C> 用法: <c>text</c> 将说明中的文本标记为代码.例如: ...

随机推荐

  1. Windows下Python虚拟环境

    python的虚拟环境在windows和linux下的配置是不一样的 主要解决开发应用程序的时候Python依赖包的版本问题 虚拟环境 virtualenv 安装 pip install virtua ...

  2. JVM-1-HotSpot server client

    64位JDK 默认只能工作在Server模式下 是无法切换到Client模式的   Hot Spot虚拟机Server

  3. 一、itk在VS2019上面的安装 和例子(HelloWorld)运行

    一.Itk简介 vtk是专门用于医疗图像处理的函数库,类似opencv. 这篇博客主要是讲解安装vtk之后的例子的运行,即如何构建自己的第一个ITK例子 二.Itk安装 Itk安装参考这篇博客: ht ...

  4. verilog 基础知识

    mealy型状态机的下一状态和输出取决于当前状态和当前输入: moore型状态机的下一状态和输出取决于当前状态和当前输入,但其输出仅取决于现在的状态: 基本门原语的输出端口必须写在端口列表的前面,基本 ...

  5. number.toFixed和Math.round与保留小数

    如果你baidu/google过或者自己写过保留两位小数,那下面这代码一定不陌生 Math.round(number*100)/100 那你使用过Number.prototype.toFixed这个方 ...

  6. IDEA springboot配置

    基于springboot2.1.7 springboot项目创建 springboot热部署 springboot配置swagger2 springboot配置mybatis springboot配置 ...

  7. vscode源码分析【四】程序启动的逻辑,最初创建的服务

    第一篇: vscode源码分析[一]从源码运行vscode 第二篇:vscode源码分析[二]程序的启动逻辑,第一个窗口是如何创建的 第三篇:vscode源码分析[三]程序的启动逻辑,性能问题的追踪 ...

  8. Linux 学习记录五(软件的安装升级).

    一.gcc gcc是Linux上面最标准的C语言的编译程序,用来源代码的编译链接. gcc -c hello.c 编译产生目标文件hello.o gcc -O hello.c 编译产生目标文件,并进行 ...

  9. MySQL变量介绍和用法简介

    目录 一.用户变量 1.1.用户变量定义 1.2.用户变量用法 二.系统变量 2.1 系统变量简单介绍 2.2 系统变量用法简介 本博客介绍一下MySQL中变量的用法和注意细节 @ 一.用户变量 1. ...

  10. 转载:点云上实时三维目标检测的欧拉区域方案 ----Complex-YOLO

    感觉是机器翻译,好多地方不通顺,凑合看看 原文名称:Complex-YOLO: An Euler-Region-Proposal for  Real-time 3D Object Detection ...