专栏首页Web技术布道师每个 PHPer 都应当掌握的注释标记

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

简介

注释标签在代码注释中的作用非常大,但是可能很多同学在平常开发中会忽略这些标签的作用,所以我这边特地整理一些常用的注释标记,通过图文展现形式,希望能帮助你能更好理解每个注释标签的作用.

或许你离漂亮的代码,就差一个标签^_^

项目工程地址: https://github.com/yinggaozhen/doc-demo/tree/master/php

_

@deprecated

@deprecated : 被此标记的函数或者成员方法表示下个版本将会被废弃,告知适用方不再推荐使用此方法.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/deprecated

语法

@deprecated [<version>] [<description>]

描述

  • @deprecated 可以填写一个版本号,版本号的规则同 @version
  • 如果被标记的方法只是因为被其他新方法代替而被废弃,可以结合 @see 来表示被代替的方法

标签效果

_

@inheritdoc

@inheritdoc : 文档继承,会继承父类的文档注释.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/inheritdoc

语法

@inheritDoc

描述

  • @inheritDoc 会继承父类的所有文档注释.在继承之后可以对指定字段进行重写

标签效果

1.直接继承

2.继承重写

_

@internal

@internal : 被此标签标记的内部类/方法,作用范围只能限于当前文件,外部文件不可调用.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/internal

语法

@internal [description]

使用场景

此标签通常可使用在单元测试中,比如在单元测试中定义了一个测试用的类,可对此测试类添加 @internal 标签,这样别人在正常逻辑中万一不小心错误引用了测试类,在IDE的帮助下,可以第一时间得到反馈.

标签效果

@link : 此标签可以引导你到指定的 外部跳转链接 .

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/link

语法

@link [URI] [<description>]

描述

该标签只有1个跳转选项

  • @外部跳转链接 : 必须是满足 RFC2396 的跳转链接,例如 http://github.com/yinggaozhen

和@see的区别

-

@see

@link

外部链接

内部程序

X

_

@see

@see : 此标签可以引导你到指定的 外部跳转链接 / 内部程序 .

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/see

语法

@see [URI | FQSEN] [<description>]

描述

该标签可以有两个跳转选项

  • @外部跳转链接 : 必须是满足 RFC2396 的跳转链接,例如 http://github.com/yinggaozhen
  • @内部程序链接 : 可以跳转到制定的类/方法/变量,如class::method

和@link的区别

-

@see

@link

外部链接

内部程序

X

_

@var

@var : 定义一个数据的类型.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/var

语法

@var [Type] [$element_name] [<description>]

变量列表

变量类型

说明

string

字符串

integer/int

number/int类型

boolean/bool

false/true

float/double

number/浮点数

object

对象实例

specifiedType

指定类

mixed

任意类型

array/specifiedType[]

数组,可以指定成指定类型的数组

resource

文件资源类型

void

无返回值

null

-

callable

可执行的回调函数

function

不一定能执行的方法

self/$this

当前实例

标签效果

实现@var可以有两种使用方法

1.在类成员变量中定义,不需要指定变量名称

2.直接给具体变量定义,需要指定变量名称

_

@throws

@throws : 抛出一个异常,告诉调用方需要做好处理异常相关工作.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/php/throws

语法

@throws [Type] [<description>]

标签效果

_

最后

文章篇幅有限,这里列举了一部分标签,更多标签可以通过以下工程地址

项目工程地址: https://github.com/yinggaozhen/doc-demo/tree/master/php

本文分享自微信公众号 - PHP技术大全(phpgod)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-06-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 【鸟哥】PHP7强悍性能背后,zval的变化!

    PHP7已经发布, 如承诺, 我也要开始这个系列的文章的编写, 主要想通过文章让大家理解到PHP7的巨大性能提升背后到底我们做了什么, 今天我想先和大家聊聊zv...

    猿哥
  • 【干货】PHP7强悍性能背后,zval的变化!

    PHP7已经发布, 如承诺, 我也要开始这个系列的文章的编写, 主要想通过文章让大家理解到PHP7的巨大性能提升背后到底我们做了什么, 今天我想先和大家聊聊zv...

    猿哥
  • 前端HTML空格与后台PHP utf-8空格

    在用户名输入框中输入admin "'p(中间是一个空格),点保存后台提示数据保存成功,按理应该是未修改,通过chrome调试工具发现传给后台的数据却是这样的:

    猿哥
  • 提示可能你的react函数组件从来没有优化过React.memome

    当16.6的memo问世,函数组件就有了类似PureComponent和shouldComponentUpdate的解决方案,memo的使用方法:

    lhyt
  • 快速学习-JPA中的一对多

    在一对多关系中,我们习惯把一的一方称之为主表,把多的一方称之为从表。在数据库中建立一对多的关系,需要使用数据库的外键约束。

    cwl_java
  • 腾讯云认证考试常见问题答疑

    认证报名官网:https://cloud.tencent.com/edu/training,您需要先注册腾讯云帐号,并通过个人身份认证,完成个人认证后在该页面选...

    KLKL
  • DeepMind首次走出英国根据地,在埃德蒙顿创建实验室

    安妮 编译整理 量子位出品 | 公众号 QbitAI 昨天,DeepMind在加拿大埃德蒙顿建立了首个国际AI实验室。这是DeepMind自2014年被谷歌收购...

    量子位
  • 可能你的react函数组件从来没有优化过

    当16.6的memo问世,函数组件就有了类似PureComponent和shouldComponentUpdate的解决方案,memo的使用方法:

    IMWeb前端团队
  • 「深度」跨越一甲子的AI已在何处迎来爆发?16位顶级专家给出了答案

    镁客网
  • Android开发笔记(四十九)异步任务处理AsyncTask

    Thread+Handler方式虽然能够实现多线程的通信处理,但是写起代码来颇为繁琐,所以Android提供了AsyncTask这样一个轻量级的异步任务类,...

    用户4464237

扫码关注云+社区

领取腾讯云代金券