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 相关文章推荐
利用discuz自带通行证整合dedecms的方法以及文件下载
Mar 06 PHP
zend api扩展的php对象的autoload工具
Apr 18 PHP
php在线代理转向代码
May 05 PHP
PHP运行模式的深入理解
Jun 03 PHP
解决FastCGI 进程超过了配置的活动超时时限的问题
Jul 03 PHP
phplot生成图片类用法详解
Jan 06 PHP
php对数组内元素进行随机调换的方法
May 12 PHP
PHP的serialize序列化数据以及JSON格式化数据分析
Oct 10 PHP
详解WordPress中分类函数wp_list_categories的使用
Jan 04 PHP
php基于PDO实现功能强大的MYSQL封装类实例
Feb 27 PHP
Laravel 加载第三方类库的方法
Apr 20 PHP
PHP7 list() 函数修改
Mar 09 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笔记之:文章中图片处理的使用
2013/04/26 PHP
Laravel执行migrate命令提示:No such file or directory的解决方法
2016/03/16 PHP
PHP中PDO连接数据库中各种DNS设置方法小结
2016/05/13 PHP
PHP面向对象程序设计之接口的继承定义与用法详解
2018/12/20 PHP
JS实现切换标签页效果实例代码
2013/11/01 Javascript
百度地图api如何使用
2015/08/03 Javascript
jQuery抛物线运动实现方法(附完整demo源码下载)
2016/01/08 Javascript
通过jquery-ui中的sortable来实现拖拽排序的简单实例
2016/05/24 Javascript
JavaScript中输出信息的方法(信息确认框-提示输入框-文档流输出)
2016/06/12 Javascript
AngularJS使用指令增强标准表单元素功能
2016/07/01 Javascript
bootstrap实现图片自动轮播
2016/12/21 Javascript
原生js实现节日时间倒计时功能
2017/01/18 Javascript
JS实现匀速与减速缓慢运动的动画效果封装示例
2018/08/27 Javascript
ES6中字符串的使用方法扩展
2019/06/04 Javascript
基于vue和websocket的多人在线聊天室
2020/02/01 Javascript
详解Node.JS模块 process
2020/08/31 Javascript
用Python解析XML的几种常见方法的介绍
2015/04/09 Python
PyQt5 QTableView设置某一列不可编辑的方法
2019/06/25 Python
pytorch中的embedding词向量的使用方法
2019/08/18 Python
python os模块在系统管理中的应用
2020/06/22 Python
Tensorflow tensor 数学运算和逻辑运算方式
2020/06/30 Python
python如何实现读取并显示图片(不需要图形界面)
2020/07/08 Python
DBA的职责都有哪些
2012/05/16 面试题
什么是Linux虚拟文件系统VFS
2015/08/25 面试题
大学生简历的个人自我评价
2013/12/04 职场文书
运动会稿件100字
2014/02/21 职场文书
施工员岗位职责
2014/03/16 职场文书
学习交流会主持词
2014/04/01 职场文书
《真想变成大大的荷叶》教学反思
2014/04/14 职场文书
演讲稿格式范文
2014/05/19 职场文书
反对邪教标语
2014/06/30 职场文书
信仰心得体会
2014/09/05 职场文书
党员评议思想汇报
2014/10/08 职场文书
单身证明范本
2015/06/15 职场文书
电脑关机速度很慢怎么办 提升电脑关机速度设置教程
2022/04/08 数码科技
解决IIS7下无法绑定https主机的问题
2022/04/29 Servers