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 调试环境(IIS+PHP+MYSQL)
Jan 10 PHP
php 中的str_replace 函数总结
Apr 27 PHP
PHP根据IP地址获取所在城市具体实现
Nov 27 PHP
php中的静态变量的基本用法
Mar 20 PHP
推荐25款php中非常有用的类库
Sep 29 PHP
php实现通过ftp上传文件
Jun 19 PHP
[原创]ThinkPHP让../Public在模板不解析(直接输出)的方法
Oct 09 PHP
yii用户注册表单验证实例
Dec 26 PHP
Smarty保留变量用法分析
May 23 PHP
PHP使用curl函数发送Post请求的注意事项
Nov 26 PHP
PHP的mysqli_stat()函数讲解
Jan 23 PHP
Laravel的加密解密与哈希实例讲解
Mar 24 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
FireFox浏览器使用Javascript上传大文件
2013/10/30 PHP
php实现zip文件解压操作
2015/11/03 PHP
php 使用curl模拟ip和来源进行访问的实现方法
2017/05/02 PHP
PHP中“=&gt;
2019/03/01 PHP
PHP 实现重载
2021/03/09 PHP
定义JavaScript二维数组采用定义数组的数组来实现
2012/12/09 Javascript
JavaScript的Module模式编程深入分析
2013/08/13 Javascript
JavaScript实现cookie的写入、读取、删除功能
2015/11/05 Javascript
jQuery使用serialize()表单序列化时出现中文乱码问题的解决办法
2016/07/27 Javascript
微信小程序 SocketIO 实例讲解
2016/10/13 Javascript
详解vuejs几种不同组件(页面)间传值的方式
2017/06/01 Javascript
vue: WebStorm设置快速编译运行的方法
2018/10/18 Javascript
创建echart多个联动的示例代码
2018/11/23 Javascript
使用watch在微信小程序中实现全局状态共享
2019/06/03 Javascript
JS实现动态添加外部js、css到head标签的方法
2019/06/05 Javascript
mustache.js实现首页元件动态渲染的示例代码
2020/12/28 Javascript
为Python的web框架编写MVC配置来使其运行的教程
2015/04/30 Python
详解Python import方法引入模块的实例
2017/08/02 Python
解决python升级引起的pip执行错误的问题
2018/06/12 Python
Empty test suite.(PyCharm程序运行错误的解决方法)
2018/11/30 Python
python机器人运动范围问题的解答
2019/04/29 Python
Python中字符串与编码示例代码
2019/05/20 Python
Python爬虫动态ip代理防止被封的方法
2019/07/07 Python
利用Python实现Shp格式向GeoJSON的转换方法
2019/07/09 Python
深入学习python多线程与GIL
2019/08/26 Python
Python hashlib加密模块常用方法解析
2019/12/18 Python
Python concurrent.futures模块使用实例
2019/12/24 Python
Python3 实现爬取网站下所有URL方式
2020/01/16 Python
django实现日志按日期分割
2020/05/21 Python
FLOS美国官网:意大利高级照明工艺的传奇
2018/08/07 全球购物
Myprotein西班牙官网:欧洲第一大运动营养品牌
2020/02/24 全球购物
应届生自荐信
2014/06/30 职场文书
旅游专业毕业生自荐书
2014/06/30 职场文书
宣传部部长竞选稿
2015/11/21 职场文书
2019年度政务公开考核工作总结模板
2019/11/11 职场文书
Java中多线程下载图片并压缩能提高效率吗
2021/07/01 Java/Android