php 注释规范


Posted in PHP onMarch 29, 2012

用过IDE或看过其他源码的小伙伴们应该都见过类似下面这样的注释

/**
 * 递归获取所有游戏分类
 * @param int $id
 * @return array
 */

看得多了就大概知道了一些规律。为了使自己的代码更加规zhuang范bi,也开始有样学样地写着这些注释

其实这种注释格式是有自己的名字的,它就叫——

PHPDOC

PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档,也可以帮助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之类的 集成开发环境 理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成,类型提示和除错功能。
PHPDoc 可同时支持 面向对象 的和 面向过程的 代码。

以上摘自维基百科
简单来说PHPDOC可以用来自动生成API文档。主流的IDE都会识别它,并在你coding中给予你相应的智能提示。使用PHPDOC有以下好处

  • 让你的代码更加规zhuang范bi,更易于理解

  • 让你的IDE更懂你的代码,更加智能的提示和自动完成

  • 如需API手册,可使用phpDocumentor来自动生成

还等什么?快跟我一起来学习又好用又有逼格的phpDoc吧!

有关phpDoc的完整文档位于phpDocumentor官网。以下内容由我个人理解、提炼而来,而且我也还在学习中,如有失误还请各位多多指教

@api

表示这是一个提供给第三方使用的API接口

@author

作者
格式@author [名称] [<邮箱>]
例如@author mokeyjay <i@mokeyjay.com>

@copyright

版权声明。例如很多网站底部都有
格式@copyright [描述]
例如@copyright 1949-2016 China

@deprecated

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

@example

例子、示例、用例。也可表示方法返回值的例子
格式@example [位置] [<起始行号> [<行数>] ] [<描述>]
例如@example demo.php 10 3 使用示例

@filesource

没看懂,如果你们看懂了请告诉我。传送门

@global

全局变量
格式@global [类型][名称] @global [类型][描述]
我怀疑这里是源文档打错了,大概应该是
格式@global [类型][名称][描述]
类型@global string name 用户名

@ignore

忽略
格式@ignore [<描述>]
例如你在if和else的语句块中定义分别同一个变量但值不同时,可以通过此标记让phpDocumentor忽略其中一个,以免生成重复的文档。例如

if ($ostest) {
   /**
   * This define will either be 'Unix' or 'Windows'
   */
   define("OS","Unix");
 } else {
   /**
   * @ignore
   */
   define("OS","Windows");
 }

@internal

仅限内部使用的
格式@internal [描述]
例如@internal 仅限内部测试使用

@license

协议,很常见的啦
格式@license [<url>] [名称]
例如@license GPL

@link

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

@method

方法。这是用在类注释里的标记。特别适合一些动态加载的类,IDE无法自动提示出来,这时就可以通过写@method标记来告诉IDE我这类里有哪些方法
格式@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提问,返回答案内容

@package

包。但php没有包,所以就用来表示命名空间
例如@package yii\base\db

@param

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

@property

类属性,与@method类似,可以告诉IDE我这类里有哪些属性
格式@property [Type] [name] [<description>]
例如@property int id 用户id

@property-read

只读的属性。例如__get魔术方法能够取到的属性
格式@property-read [Type] [name] [<description>]
例如@property-read int id 用户id

@property-write

只可写的属性。例如__set魔术方法能够设置的属性
格式@property-write [Type] [name] [<description>]
例如@property-write string name 用户名

@return

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

@see

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

@since

从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等
格式@since [1.0.0] [<描述>]
例如@since 1.0.2 添加了$b参数

@source

没看懂,如果你们看懂了请告诉我。传送门

@throws

可能会抛出的错误类型
格式@throws [类型] [<描述>]
例如@throws LifeException 没钱了,好想死啊

@todo

待办。提示自己或他人还需要做些什么
格式@todo [描述]
例如@todo 这个类还没做异常处理

@uses

使用
格式@uses [完整方法名] [<描述>]
例如@uses \yii\base\db::$count 使用此属性计数

@var

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

@version

版本号
格式@version [<载体>] [<描述>]
例如@version 1.0.1 2016-07-03更新
或者@version GIT:1f3197d01 来自GIT分支1f3197d01

PHP 相关文章推荐
PHP静态类
Nov 25 PHP
PHP中开启gzip压缩的2种方法
Jan 31 PHP
php把大写命名转换成下划线分割命名
Apr 27 PHP
PHP生成随机字符串(3种方法)
Sep 25 PHP
PHP中strpos、strstr和stripos、stristr函数分析
Jun 11 PHP
php  PATH_SEPARATOR判断当前服务器系统类型实例
Oct 28 PHP
详解配置 Apache 服务器支持 PHP 文件的解析
Feb 15 PHP
yii2多图上传组件的使用教程
May 10 PHP
PHP实现websocket通信的方法示例
Aug 28 PHP
深入理解 PHP7 中全新的 zval 容器和引用计数机制
Oct 15 PHP
TP5(thinkPHP5)框架使用ajax实现与后台数据交互的方法小结
Feb 10 PHP
php设计模式之策略模式实例分析【星际争霸游戏案例】
Mar 26 PHP
php 计划任务 检测用户连接状态
Mar 29 #PHP
MySQL的FIND_IN_SET函数使用方法分享
Mar 27 #PHP
php提示无法加载或mcrypt没有找到 PHP 扩展 mbstring解决办法
Mar 27 #PHP
phpMyAdmin 链接表的附加功能尚未激活问题的解决方法(已测)
Mar 27 #PHP
phpMyAdmin出现无法载入 mcrypt 扩展,请检查PHP配置的解决方法
Mar 26 #PHP
simplehtmldom Doc api帮助文档
Mar 26 #PHP
php中一个有意思的日期逻辑处理
Mar 25 #PHP
You might like
需要注意的几个PHP漏洞小结
2012/02/05 PHP
thinkPHP框架中执行原生SQL语句的方法
2017/10/25 PHP
Thinkphp5 微信公众号token验证不成功的原因及解决方法
2017/11/12 PHP
laravel 中某一字段自增、自减的例子
2019/10/11 PHP
在textarea中屏蔽js的某个function的javascript代码
2007/04/20 Javascript
jQuery(js)获取文字宽度(显示长度)示例代码
2013/12/31 Javascript
IE中的File域无法清空使用jQuery重设File域
2014/04/24 Javascript
获取阴历(农历)和当前日期的js代码
2016/02/15 Javascript
jquery动态遍历Json对象的属性和值的方法
2016/07/27 Javascript
第一次接触神奇的Bootstrap
2016/10/14 Javascript
AngularJS 应用身份认证的技巧总结
2016/11/07 Javascript
详解前后端分离之VueJS前端
2017/05/24 Javascript
react-router实现跳转传值的方法示例
2017/05/27 Javascript
vuex 的简单使用
2018/03/22 Javascript
vue+element-ui+axios实现图片上传
2019/08/20 Javascript
Vue表单提交点击事件只允许点击一次的实例
2020/10/23 Javascript
[05:10]2014DOTA2国际邀请赛 通往胜利之匙赛场探秘之旅
2014/07/18 DOTA
TensorFlow平台下Python实现神经网络
2018/03/10 Python
python selenium 对浏览器标签页进行关闭和切换的方法
2018/05/21 Python
Python 确定多项式拟合/回归的阶数实例
2018/12/29 Python
python paramiko利用sftp上传目录到远程的实例
2019/01/03 Python
python对列进行平移变换的方法(shift)
2019/01/10 Python
python设置随机种子实例讲解
2019/09/12 Python
在Python 的线程中运行协程的方法
2020/02/24 Python
关于keras.layers.Conv1D的kernel_size参数使用介绍
2020/05/22 Python
CSS3系列之3D制作方法案例
2017/08/14 HTML / CSS
俄罗斯便宜的在线服装商店:GroupPrice
2020/04/10 全球购物
成教自我鉴定
2013/10/27 职场文书
银行实习的自我鉴定
2013/12/10 职场文书
家长给幼儿园的表扬信
2014/01/09 职场文书
生物制药专业求职信
2014/03/11 职场文书
团购业务员岗位职责
2014/03/15 职场文书
暑期学习心得体会
2014/09/02 职场文书
质量保证书怎么写
2015/02/27 职场文书
党风廉政建设心得体会(2016最新版)
2016/01/22 职场文书
高一化学教学反思
2016/02/22 职场文书