您现在的位置是:门户> 编程语言> PHP

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

    用过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


分享:

文章评论