PHP注释的艺术——phpDoc规范

HtmlCssJs 发布于2019-07-01 14:17 / 1186人阅读

摘要：特别适合一些动态加载的类，无法自动提示出来，这时就可以通过写标记来告诉我这类里有哪些方法格式返回值类型名称类型参数描述例如向谷歌提问，返回答案内容包。

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

@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 [] [名称]
例如@license GPL

@link

链接，可用于辅助说明、引用文档等
格式@link [url] [<描述>]
例如@link http://g.cn 不懂滚去问谷歌，别来烦我

@method

方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE无法自动提示出来，这时就可以通过写@method标记来告诉IDE我这类里有哪些方法
格式@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提问，返回答案内容

@package

包。但php没有包，所以就用来表示命名空间
例如@package yiiasedb

@param

参数，用于函数和方法注释里的标记
格式@param [Type] [name] []
例如@param string title 文章标题

@property

类属性，与@method类似，可以告诉IDE我这类里有哪些属性
格式@property [Type] [name] []
例如@property int id 用户id

@property-read

只读的属性。例如__get魔术方法能够取到的属性
格式@property-read [Type] [name] []
例如@property-read int id 用户id

@property-write

只可写的属性。例如__set魔术方法能够设置的属性
格式@property-write [Type] [name] []
例如@property-write string name 用户名

@return

返回值
格式@return [类型] [<描述>]]
例如@return array 结果数组

@see

参考，类似@link，可与@deprecated联动
格式@see [url或完整方法名] [<描述>]
例如@see yiiasedb::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 yiiasedb::$count 使用此属性计数

@var

变量
格式@var [类型] [变量名] [<描述>]
例如@var int id 用户id

@version

版本号
格式@version [<载体>] [<描述>]
例如@version 1.0.1 2016-07-03更新
或者@version GIT:1f3197d01 来自GIT分支1f3197d01

本文同时刊登于我的博客超能小紫，如果喜欢请常来玩哦

专线服务云服务器注释规范 java代码注释规范 php广泛应用的规范 php的注释符

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/31946.html

正确注释@return让PHPstorm动态返回类

摘要：大意就是和差不多，但是父类方法子类调用，仍然返回父类。这个确切的对象实例，通常用于表示流畅的界面。这次我才真正意识到了注释的重要性。。。最后，因为并不是我一个人在写，所以没有办法进行大刀阔斧地改动，只能尽可能地优化。场景是这样的，有一个BaseModel（继承自ActionRecord），所有的其他model都继承自它，然后其中有一个方法，简单贴下这个类的代码，： class Bas...

simon_chen 2019-07-01 10:23 评论0 收藏0
php-cs-fixer - PHP 编码格式化工具

摘要：是个代码格式化工具，格式化的标准是以及一些的标准。这个工具也和等优秀的库出自同门。如果同时设定了和，前者的优先级更高。同时使用和命令可以显示出需要修改的汇总，但是并不实际修改。你可以设置格式化的选项级别文件以及目录。 php-cs-fixer 是个代码格式化工具，格式化的标准是 PSR-1、PSR-2 以及一些 symfony 的标准。这个工具也和 symfony、twig 等优秀的 ...

ityouknow 2019-06-27 11:50 评论0 收藏0
如何成为一名优秀的工程师（语义篇）

摘要：好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。日常中应该多多刻意提升自己语义表达，百利而无一害。注释更多参考函数方法案例先说明一句，不好的代码不妨碍它成为一个优秀的软件。这是非常不友好的语义表达。好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。本篇文章巨长，如果你比较懒，来我讲给你听（直播中有更多细节） ...

张金宝 2019-07-01 12:33 评论0 收藏0
在github规范开发以及持续构建php项目

摘要：本文目的是通过自己写的一个的简单的库花密密码生成工具，来学习我认为的库开发的一些规范，以及上持续构建你的项目的一些方法。给自己的项目开启持续构建。包发布以及当你的代码完成后，测试完成后。本文目的是通过自己写的一个php的简单的库（花密密码生成工具），来学习我认为的php库开发的一些规范，以及github上持续构建你的项目的一些方法。其实是为了显示下边一系列的的徽章 showImg(...

Sleepy 2019-06-27 15:06 评论0 收藏0
swagger系列一：laravel中部署swagger ui

摘要：部署到项目中可以下来也可以下载文件。解压后把目录下的目录拷贝到下下的文件夹中，如新建。访问修改为自己的项目文件。找到，把修改为自己的，如，再次访问即可。但是并不存在，需要生成。如放在下的目录，用于存放文件。 1. 部署swagger ui 到项目中：可以Git下来 git clone https://github.com/swagger-api/swagger-uiv也可以下载zi...

lookSomeone 2019-06-28 18:39 评论0 收藏0