"phpdocumentor/phpdocumentor": "2.*"生成API文档

逃离我推掉我的手 2022-05-31 03:24 186阅读 0赞

PHPDocumentor是一个用PHP写的强大的文档自动生成工具，对于有规范注释的php[程序][Link 1]，能够快速生成具有结构清晰、相互参照、索引等功能的API文档。旧版本是PHPDoc，PHPDoc是PEAR下面的一个非常优秀的模块，类似于[Java][]doc。从1.3.0开始，更名为phpDocumentor，新版本新加了对php5语法的支持，同时，可以通过在[客户端][Link 2][浏览器][Link 3]上操作生成文档，文档可以转换为PDF、HTML、CHM等格式的文档，这样非常有利于代码的升级、维护、移交等。

官网地址:[https://www.phpdoc.org/][https_www.phpdoc.org]

前提：安装的前提是已经安装了php环境，我安装的是xampp集成开发环境。

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

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

第一种方法：   
第一步：安装pear   
使用dos窗口进入php安装目录，有个文件叫go-pear.bat，如果没有，建议到网上下载go-pear.phar，然后在dos窗口下运行 go-pear.phar, 从而安装pear。

php go-pear.phar

第二步：安装phpdoc

Pear install phpDocumentor

在phpDocumentor成功安装后，php安装目录下会多出来一个phpdoc.bat。这个文件就是我们用来生成文档的批处理文件。   
在phpdoc.bat所在目录下\_(是/vendor/bin/ 目录下,不是vendor\\phpdocumentor\\phpdocumentor\\bin目录)，输入

Phpdoc –h

会得到一个phpDocumentor的详细参数列表。先看看最重要的几个吧。

-d 这个目录代表着需要生成文档的api原始php文件目录（注意是目录） -t 这个目录代表着生成的文档存放目录 -o 这个参数代表着生成的文档格式，例如html格式，参数就是 HTML:frames:phpedit

第三步：生成文档

[https://github.com/phpDocumentor/phpDocumentor2 ][https_github.com_phpDocumentor_phpDocumentor2]查看使用方法

查看帮助： phpdoc run -h  
生成文档的命令就是：

phpdoc run -d D:\phpdoc\api -t D:\phpdoc\view

![生成的html文件][html]

可以看到，解析完成后，在目标目录下生成很多html文件，打开index.html文件，就是我们需要的文档，如下图所示。

![生成的类参考文档][1848313300948142.jpg]

第二种方法：   
第一步：下载PHPDoc压缩文件（phpdoc.zip），地址如下：   
http://star7th-wordpress.stor.sinaapp.com/uploads/2013/04/phpdoc.zip

第二步：解压到某一个目录   
打开phpdoc.bat，编辑第16行：

SET phpCli=D:\xampp\php\php.exe

配置phpCli 为自己php.exe文件的路径即可。

第二步：dos窗口，进入文件的解压目录，然后执行解析文档命令即可。

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1" -o "HTML:frames:phpedit"

以上是安装phpDocumentor1版本，目前已经更新到phpDocumentor2版本了，[version][]2的安装也很简单。

第一步：安装pear（同上）   
此处给出下载地址：http://pear.php.net/go-pear.phar   
将 go-pear.phar 放到 PHP 目录下执行安装命令：

php go-pear.phar

下面会执行输入 [system][]

然后一路回车安装完毕。

第二步：接下来安装类关系绘图用到的工具

pear install image\_graphviz   
下载 http://www.graphviz.org/Download\_[Windows][].php graphviz-2.38.msi   
安装后，注意环境变量 path 添加上该 bin 的路径，重启[电脑][Link 8]，否则无法生效

第三步：安装 phpDocumentor

pear channel-discover pear.phpdoc.org pear install phpdoc/phpDocumentor

稍等一会，安装步骤完成！   
注意：两个[软件][Link 9]安装后的目录都在PHP 下的 pear 下面：

php/pear/PhpDocumentor
    php/pear/Image

显然：version2 比version1速度快了很多。

[Link 1]: http://www.07net01.com/tags-%E7%A8%8B%E5%BA%8F-0.html
[Java]: http://www.07net01.com/tags-Java-0.html
[Link 2]: http://www.07net01.com/tags-%E5%AE%A2%E6%88%B7%E7%AB%AF-0.html
[Link 3]: http://www.07net01.com/tags-%E6%B5%8F%E8%A7%88%E5%99%A8-0.html
[https_www.phpdoc.org]: https://www.phpdoc.org/
[Link 4]: http://www.07net01.com/tags-%E5%B7%A5%E4%BD%9C%E5%8E%9F%E7%90%86-0.html
[Link 5]: http://www.07net01.com/tags-%E6%BA%90%E4%BB%A3%E7%A0%81-0.html
[Link 6]: http://www.07net01.com/tags-%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F-0.html
[Link 7]: http://www.07net01.com/tags-%E6%8E%A5%E5%8F%A3-0.html
[https_github.com_phpDocumentor_phpDocumentor2]: https://github.com/phpDocumentor/phpDocumentor2
[html]: http://img4.07net01.com/upload/images/2015/12/30/1848313300948141.jpg
[1848313300948142.jpg]: http://img4.07net01.com/upload/images/2015/12/30/1848313300948142.jpg
[version]: http://www.07net01.com/tags-version-0.html
[system]: http://www.07net01.com/tags-system-0.html
[Windows]: http://www.07net01.com/
[Link 8]: http://www.07net01.com/tags-%E7%94%B5%E8%84%91-0.html
[Link 9]: http://www.07net01.com/ruanjiantuijian/