PHPDoc 规范

转载自 PHP 注释的艺术 —— phpDoc 规范

PHPDOC


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

以上摘自维基百科

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

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

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

  3. 如需 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 注释的艺术 —— phpDoc 规范

其他文章链接

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

PHPDOC参考文档

  • 0
    点赞
  • 5
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值