PHP 注释标记,

相关标签

@author

@author当前文件的作者

语法

@author [name] [<\email address>]

描述

@author可以后边包含作者电子邮箱,通常电子邮箱由<>包裹

@deprecated

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

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

描述

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

[@example](https://learnku.com/users/20807)

@inheritdoc

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@inheritDoc

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

标签效果

直接继承

PHP 注释标记,

继承重写

PHP 注释标记,

@link

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@link [URI] [<\description>]

描述

该标签只有1个跳转选项

和@see的区别

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

@method

@method : 此标签可告诉类有哪些魔术方法可以调用.

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@method [modifier] [return type] [name]([[type] [parameter]<, …>]) [<\description>]

使用场景

当一个类用魔术方法__call去代理执行类成员方法时,对于调用方来讲是很迷茫的,因为调用方是无法知道具体有哪些方法可以调用. 通过引入@method可以解决这个问题,可以在类注释添加@method,定义魔术方法可调用的方法,这样调用法可以通过查看注释即可知道如何调用魔术方法,部分IDE可直接识别@method标签从而实现自动填充以及类型判断.

标签效果

IDE自动提示

PHP 注释标记,

最终效果

PHP 注释标记,

@mixin

@param

@param : 可以记录函数/方法的单个入参的信息.

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@param [Type] [name] [<\description>]

变量列表

PHP 注释标记,

标签效果

PHP 注释标记,

@property

@property : 当类中包含魔术方法get/set时,可以通过此标签定义名称.

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@property [Type] [name] [<\description>]

使用场景

当一个类用魔术方法__get或者__set去代理执行类成员变量时,对于调用方来讲是很迷茫的,因为调用方是无法知道具体有哪些成员. 通过引入@property可以解决这个问题,可以在类注释添加@property定义成员变量,这样调用法可以通过查看注释即可知道具体有哪些成员变量可以使用,部分IDE可直接识别@property标签从而实现自动填充以及类型判断.

变量列表

PHP 注释标记,

标签效果

IDE自动提示

PHP 注释标记,

最终效果

PHP 注释标记,

[@return](https://learnku.com/users/31554)

[[@return](https://learnku.com/users/31554)](https://learnku.com/users/31554)](https://learnku.com/users/31554)](https://learnku.com/users/31554) : 用于在函数/方法返回值信息.

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

[[[@return](https://learnku.com/users/31554)](https://learnku.com/users/31554)](https://learnku.com/users/31554) [Type] [<\description>]

变量列表

PHP 注释标记,

标签效果

PHP 注释标记,

@see

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

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

描述

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

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

和@link的区别

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

@throws

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@throws [Type] [<\description>]

标签效果

PHP 注释标记,

@var

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

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

变量列表

PHP 注释标记,

标签效果
在类成员变量中定义,不需要指定变量名称

PHP 注释标记,

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

PHP 注释标记,

@internal

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

此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用

语法

@internal [\description]

使用场景

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

标签效果

PHP 注释标记,

@version

@copyright

@license

@since

@package

@todo

注释规范

  • 对于引用了全局变量的函数,必须使用@glboal标记
  • 对于变量,必须用@var标记其类型(int,string,bool…)
  • 函数必须通过@param[[[[@return](https://learnku.com/users/31554)](https://learnku.com/users/31554)](https://learnku.com/users/31554)](https://learnku.com/users/31554)标记指明其参数和返回值
  • 对于出现两次或两次以上的关键字,要通过@ingore忽略掉多余的,只保留一个即可
  • 调用了其他函数或类的地方,要使用@link或其他标记链接到相应的部分,便于文档的阅读。
  • 必要的地方使用非文档性注释,提高代码易读性。
  • 描述性内容尽量简明扼要,尽可能使用短语而非句子。
  • 全局变量,静态变量和常量必须用相应标记说明

参考文档

https://github.com/yinggaozhen/doc-demo/tr...

本作品采用《CC 协议》,转载必须注明作者和本文链接
本帖由系统于 4年前 自动加精
讨论数量: 2

对于 @inheritDoc ,在 PHPstorm 中,可以把光标放到方法上按 Ctrl + J (win 是 Ctrl + Q)直观显示方法文档提示

4年前 评论
一冉再

这个是相当重要的,可惜很少会有人花十分钟系统的学习这个东西

4年前 评论
UKNOW 4年前

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