phpdoc注释规范 - apigen的使用

  1. 试用
  2. 浏览体验好像不是很好

  • 作者：KK

  • 发表日期：2016.9.16

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

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

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

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

试用

先创建一个测试目录（比如我用的是“D:\test”），在目录里面创建这个类（文件名随便，比如我起名为test.php）：

<?php
/**
 * MySql操作类
 * @author 张三
 */
class MySql{
	/**
	 * 服务器主机
	 */
	public $host;
	
	/**
	 * 连接服务器
	 * @param boolean $isPConnect 是否建立长连接
	 * @return boolean
	 */
	public function connect($isPConnect = false){}
}

在apigen.phar所在的文件夹下执行以下命令：

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

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

浏览效果：

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

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

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

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

重复运行生成命令可能会提示：

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

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

浏览体验好像不是很好

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

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

详细使用请访问GitHub上的 yiisoft/yii2-apidoc项目，我以后会写相关文章的