PHPDoc/PHPDocumentor生成API文档

图片
0 420
lveven 2018-2-24发布
签名:欢迎访问徕问社区!

一.定义:

1.PHPDoc的结构及功能 
   PHPDoc是全部采用OOP的思想来编写的,这也是PEAR所推荐的方式,PHPDoc的工作原理:PHPDoc扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,然后分析注释中的专用的tag,生成xml文件,接着根据已经分析完的类和模块的信息,建立相应的索引,生成xml文件对于生成的xml文件,使用定制的模板输出为html文件。从设计上来说,PHPDoc使用了2个超类:PhpdocObject和PhpdocError。这是整个PHPDoc的基本类,这种方式也是PEAR所推荐的。当你编写应用框架时,最好能够有一个基本的超类,而其他的子类或者是功能类都有一个共同的祖先。在扫描源代码过程中,PHPDoc使用的是类似GREP的形式。PHPDoc令人满意的另一方面是其分析结果是以XML形式保存的,这就意味着其他应用程序可以共享这个数据,同时PHPDoc也提供了相应的接口,你可以实现这个接口,把API文档生成其他的形式,比如PDF,LATEX,WORD等。目前,PHPDoc的分析结果可以以HTML形式表现,由于使用了模板机制,可以很方便地定制风格。

2.安装PHPDoc 
  安装方式有两种,一是下载源码安装,另一种是通过pear安装。

二.安装:

我实验的环境是win8 + wamp集成环境(php5.4.16),

首先是查看自己的php.exe同目录下是否存在pear这个文件,比如我的php.exe是E:\wamp\bin\php\php5.4.16

如果没有就点击这个http://pear.php.net/go-pear.phar下载go-pear.phar文件,然后将下载的文件放到php.exe同目录下,比如我的是放在E:\wamp\bin\php\php5.4.16

为了防止出现权限不够导致的错误(以前就被坑过),我使用管理员的权限(这个很重要)进入到dos,win8如下

Image(50)

其他的win系统可以查看 http://jingyan.baidu.com/article/e73e26c0f87c2424adb6a7f1.html

然后在dos命令行中切换到php.exe目录下,输入php go-pear.phar,如下图:

Image(51)

按回车默认system然后继续。以下是默认的pear的临时、数据、配置、测试、执行目录的设置:

Image(52)

按下回车提示如下:

Image(53)

就这么简单的安装成功了,查看php.exe同目录就可以看到pear这个文件了

然后执行操作 pear install PhpDocumentor

Image(54)

上面那个警告说明PhpDocumentor已经不是最新的了,以后用phpdocumentor这种写法(pear install phpdocumentor)

看到这个install ok 就说明PhpDocumentor安装成功了!

同时在我的这个目录下

E:\wamp\bin\php\php5.4.16\pear

会有以下文件

Image(55)

三.使用PhpDocumentor

输入phpdoc -h会有以下提示

Image(56)

用到最多的几个参数:

-f 要进行分析的文件名,多个文件用逗号隔开 
-d 要分析的目录,多个目录用逗号分割 
-t 生成的文档的存放路径 
-o 输出的文档格式,结构为输出格式:转换器名:模板目录。

执行以下命令:

phpdoc -o HTML:frames:earthli -f E:\www\webdev2\trunk\include\Controller\EsfController.php -t docs    (其中EsfController.php是php代码的路径, docs是生成的html API的存放路径)

Image(57)

Image(58)

然后查看docs的目录如下会有html API

E:\wamp\bin\php\php5.4.16\docs\Include\Controller

Image(59)

用浏览器访问那个API会得到如下结果

image



注释格式:

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


打赏我,让我更有动力~

收藏   0 | Support  0 | Against  0
Login | Register Can Publish Content

精美音乐推荐

最近热帖
window + php 安装redis扩展 0
返回顶部