phpapigen,apigen的使用

phpdoc注释规范 - apigen的使用 ¶

作者&＃xff1a;KK

发表日期&＃xff1a;2016.9.16

后面的学习中我会使用一个叫apigen的工具来演示生成文档&＃xff0c;所以希望你也下载跟着尝试

为了保证你的测试效果和我的一样&＃xff0c;目前我使用apigen 4.1版&＃xff0c;点击下载我共享到百度云的4.1版吧

顺便贴上apigen的官网&＃xff1a;http://www.apigen.org&＃xff0c;在首页就能找到最新版的下载地址

下载来的是一个phar文件&＃xff0c;然后将php目录添加到PATH实现在命令行能快速运行php命令就可以开始使用

试用 ¶

先创建一个测试目录(比如我用的是“D:\test”)&＃xff0c;在目录里面创建这个类(文件名随便&＃xff0c;比如我起名为test.php)&＃xff1a;

/**

* MySql操作类

* &＃64;author 张三

*/

class MySql{

/**

* 服务器主机

*/

public $host;

/**

* 连接服务器

* &＃64;param boolean $isPConnect 是否建立长连接

* &＃64;return boolean

*/

public function connect($isPConnect &＃61; false){}

}

在apigen.phar所在的文件夹下执行以下命令&＃xff1a;

php apigen.phar generate -s D:\test -d D:\apidoc

就会在D:\apidoc目录下输出生成的文档&＃xff0c;是HTML格式的&＃xff0c;直接从index.html开始双击用浏览器查看就可以了

浏览效果&＃xff1a;

然后其实无论D:\test目录里有多少类&＃xff0c;它都会找到符合phpdoc的注释生成网页文档

如果生成失败&＃xff0c;那可能是非法的phpdoc注释&＃xff0c;无法被识别

如果有一部分是phpdoc&＃xff0c;又有一部分不是&＃xff0c;却一丁点都没生成出来&＃xff0c;那可以想像的就是非phpdoc注释的部分语法导致解析器出错&＃xff0c;所以全部工作停了下来导致一个文档都没生成&＃xff0c;这种情况好像很少吧

我尝试把ThinkPHP 5.0正式版的代码解压进去再生成文件都是可以的

重复运行生成命令可能会提示&＃xff1a;

Destination is not empty. Do you want to erase it? [yes]

就是说你指定的文档输出目录不是空的&＃xff0c;确认下是不是要覆盖它&＃xff0c;输入y或者yes回车吧

浏览体验好像不是很好 ¶

如果你尝试把TP框架的代码放进去(或其它框架什么的)生成文档&＃xff0c;这样会有大量的class的api文档吧&＃xff0c;可是在命名空间之间跳转浏览的体验不是很舒服

所以其实apigen这个工具我只是教大家认识一下并且拿来学习PHPDoc的&＃xff0c;我个人真正使用的是yii2-apidoc这个工具(别看它有yii2字样就以为是Yii2专属的文档生成器&＃xff0c;咱们可以用来生成通用的PHP项目API文档&＃xff0c;只是这个生成器基于Yii2框架开发而已)