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

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

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

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

PHPDOC

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

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

  • 让你的代码更加规zhuangbi,更易于理解

  • 让你的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 [<描述>]
例如你在ifelse的语句块中定义分别同一个变量但值不同时,可以通过此标记让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注释-----PHPDOC的更多相关文章

  1. php 魔术方法,未声明属性,数组的注释 - 帮助ide跳转,提高可读性

    本人使用vscode编辑器.其他编辑器未测试. 经过1: 用laravel开发了一段时间,最麻烦的一点就是许多时候编辑器无法智能提示和辅助跳转. 有一款ide-helper的插件,感觉不是很好用,经常 ...

  2. zend studio 的使用

    1.将php项目导入到zend studio 中的方式为:http://my.oschina.net/maomi/blog/86077: 2.zend studio中将php项目导出的方式为:如果你会 ...

  3. Zend Studio 12.0.2正式版发布和破解方法,zend studio 12.0.1汉化,相式设置为Dreamweaver,空格缩进为4个, 代码默认不折叠的设置,Outline中使用的图形标志,代码颜色之eot设置。

    背景:zend studio 12.0.2 修复了一个12.0.1的:  Fixed problem with referenced variables marked as undefined,我都说 ...

  4. zend studio 10 字体,颜色,快捷键等相关设置

    一.修改字体 没想到zend studio 10中对中文显示不太好看,似乎有点小了.修改如下:打开 Window->Preferences->General->Appearance- ...

  5. PHP之道 - php各方面的知识汇总

    看到一个PHP的知识各方面的汇总,写的很有借鉴意义,搬过来了 转自: https://laravel-china.github.io/php-the-right-way/ 欢迎阅读 其他语言版本 参与 ...

  6. zend studio 提升开发效率的快捷键及可视化订制相关设置

    Zend studio快捷键使用 F3 快速跳转到当前所指的函数,常量,方法,类的定义处,相当常用.当然还可以用Ctrl+鼠标左键 shift+end 此行第一个到最后一个 shift+home 此行 ...

  7. PHP经验——PHPDoc PHP注释的标准文档(翻译自Wiki)

    文档注释,无非“//”和“/**/”两种 ,自己写代码,就那么点,适当写几句就好了:但是一个人总有融入团队的一天,团队的交流不是那几句注释和一张嘴能解决的,还需要通用的注释标准. PHPDoc是PHP ...

  8. phpDoc 注释案例说明

    <?php /** * start page for webaccess * * PHP version 5 * * @category PHP * @package PSI_Web * @au ...

  9. [转]PHP经验——PHPDoc PHP注释的标准文档

    文档翻译自:http://en.wikipedia.org/wiki/Phpdoc 标记 用途 描述 @abstract   抽象类的变量和方法 @access public, private or ...

随机推荐

  1. 用CMakeLists.txt组织工程

    1 一个工程会有多个CMakeLists.txt,如何组织这些CMakeLists.txt来构建一个工程? 1.1  最外层一个CMakeLists.txt,是总的CMakeList.txt,在这个里 ...

  2. 镜像回源主要用于无缝迁移数据到OSS,即服务已经在自己建立的源站或者在其他云产品上运行,需要迁移到OSS上,但是又不能停止服务,此时可利用镜像回写功能实现。

    管理回源设置_管理文件_开发指南_对象存储 OSS-阿里云 https://help.aliyun.com/document_detail/31865.html 通过回源设置,对于获取数据的请求以多种 ...

  3. python cookbook第三版学习笔记十三:类和对象(四)描述器

    __get__以及__set__:假设T是一个类,t是他的实例,d是它的一个描述器属性.读取属性的时候T.d返回的是d.__get__(None,T),t.d返回的是d.__get__(t,T).说法 ...

  4. case_for_if 各种嵌套相结合

    注明:本文是参考其他相关文章 整理,完全尊重原著作 #!/bin/bash usage() { cat << EOF EOF } main() { echo "猜分数赢大奖(0- ...

  5. 使用 Spring 容器管理 Filter

    当我们用Filter时,往往需要使用一些辅助的service,在普通的java中,只要声明(set,get方法)后在spring-application配置文件中配置就可以了,但是由于Filter与L ...

  6. mvn 创建的项目 导入到eclipse

    首先,我的工具版本如下: jdk: java version "1.6.0_10-rc2"; maven: apache-maven-3.1.0; eclipse: MyEclip ...

  7. 51Nod 1158 全是1的最大子矩阵 —— 预处理 + 暴力枚举 or 单调栈

    题目链接:http://www.51nod.com/onlineJudge/questionCode.html#!problemId=1158 1158 全是1的最大子矩阵  基准时间限制:1 秒 空 ...

  8. ES6 Map数据结构

    Map JavaScript 的对象(Object),本质上是键值对的集合(Hash 结构),但是传统上只能用字符串当作键.这给它的使用带来了很大的限制. ES6 提供了 Map 数据结构.它类似于对 ...

  9. WebStorm中SVN配置

    近期在使用WebStorm进行网页开发,值得一提的是WebStorm的确是一个不错的IDE,尽管可能内存开销较大,但是在编写JS的时候提供了很多包括自动完成等强大的功能. 好了,步入正题:在实际项目开 ...

  10. cmake编译成功之后VS2015可以build Solution但是不可以运行的解决办法

    1.在VS2015解决方案管理器中删除掉ALL_BUILD和ZERO_CHECK项,只保留Cmake生成的工程文件. 2.进行第一部之后还是有可能生成(build)失败,此时有可能是缺少文件.