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 多进程 解决难题
Jun 22 PHP
php网上商城购物车设计代码分享
Feb 15 PHP
xml在joomla表单中的应用详解分享
Jul 19 PHP
PHP中生成UUID自定义函数分享
Jun 10 PHP
PHP正则验证Email的方法
Jun 15 PHP
PHP中foreach()用法汇总
Jul 02 PHP
php如何实现只替换一次或N次
Oct 29 PHP
php similar_text()函数的定义和用法
May 12 PHP
Win7环境下Apache连接MySQL提示连接已重置的解决办法
May 09 PHP
PHP面向对象五大原则之接口隔离原则(ISP)详解
Apr 04 PHP
php实现微信支付之现金红包
May 30 PHP
php闭包中使用use声明变量的作用域实例分析
Aug 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实现小型站点广告管理(修正版)
2006/10/09 PHP
PHP读取文件的常见几种方法
2016/11/03 PHP
PHP延迟静态绑定使用方法实例解析
2020/09/05 PHP
一个可以显示阴历的JS代码
2007/03/05 Javascript
JavaScript 特殊字符
2007/04/05 Javascript
有关于eclipse配置spket需要注意的一些地方
2013/04/07 Javascript
js定时器(执行一次、重复执行)
2014/03/07 Javascript
jquery加载图片时以淡入方式显示的方法
2015/01/14 Javascript
jQuery插件Tmpl的简单使用方法
2015/04/27 Javascript
浅谈jQuery中replace()方法
2015/05/13 Javascript
jQuery实现的AJAX简单弹出层效果代码
2015/11/26 Javascript
JavaScript 数据类型详解
2017/03/13 Javascript
JS实现前端缓存的方法
2017/09/21 Javascript
用 js 写一个 js 解释器过程详解
2019/08/02 Javascript
JavaScript JSON数据处理全集(小结)
2019/08/15 Javascript
js实现简易拖拽的示例
2020/10/26 Javascript
[01:06:59]完美世界DOTA2联赛PWL S2 Magma vs FTD 第一场 11.29
2020/12/02 DOTA
[07:01]DOTA2-DPC中国联赛正赛 Aster vs Magma 3月5日 赛后选手采访
2021/03/11 DOTA
python中反射用法实例
2015/03/27 Python
python操作redis方法总结
2018/06/06 Python
python爬虫获取百度首页内容教学
2018/12/23 Python
python 对类的成员函数开启线程的方法
2019/01/22 Python
Pytorch实现将模型的所有参数的梯度清0
2020/06/24 Python
Python3如何在服务器打印资产信息
2020/08/27 Python
详解HTML5中的Communication API基本使用方法
2016/01/29 HTML / CSS
面试后感谢信
2014/02/01 职场文书
民族团结先进集体事迹材料
2014/05/22 职场文书
学生夜不归宿检讨书
2014/09/23 职场文书
合作协议书模板2014
2014/09/26 职场文书
普通党员群众路线教育实践活动心得体会
2014/11/04 职场文书
保证金退回承诺函格式
2015/01/21 职场文书
银行反洗钱宣传活动总结
2015/05/08 职场文书
父亲节感言
2015/08/03 职场文书
golang gopm get -g -v 无法获取第三方库的解决方案
2021/05/05 Golang
解决Python字典查找报Keyerror的问题
2021/05/26 Python
MySQL中的引号和反引号的区别与用法详解
2021/10/24 MySQL