使用yiic生成应用程序的API文档

使用yiic生成应用程序的API文档 Rate Topic: 1 Votes

#1 robhsiao

Newbie

Group: Members
Posts: 7
Joined: 02-November 10

Posted 20 November 2010 - 04:58 AM

在团队开发中，我们通常需要把API提供给其它同事参考。
Yii本身有一个生成文档的工具(http://yii.googlecod.../ApiCommand.php)，但是只能生成框架本身的文档。
并不能生成为应用程序（也就是我们自己写的业务逻辑代码）API文档。

Yii生成的文档很漂亮，并且不需要依赖 phpDocumentor。于是我自己改了改相关文件的源代码，通过Yii也可以生成应用程序的API文档。

具体怎么做？(假定我们的应用放在：/var/html/app/)

先checkout build工具：

svn co http://yii.googlecode.com/svn/tags/1.1.5/build/commands/

然后将里边的生成API的部分文件拷贝出来：

cp -r ApiCommand.php api /var/html/app/protected/commands/

进入到应用程序目录/var/html/app/protected/commands/，参考这个patch文件（也可以下载patch yiidoc.patch.txt (2.38K)
Number of downloads: 17）修改ApiCommand.php和api/ApiModel.php 两个文件
然后就可以通过
```
/var/html/app/protected/yiic api docs/
```
就会在docs这个目录生成文档了，生成的文档包含应用层的API和框架层的API

有几个注意的地方：

patch里边的 baseAppSourceUrl，可以通过它配置你公司内部的WebSVN或Trac Browser之类的工具URL。
patch中的buildModel这个函数里边包含了一个数组，array('models','components','controllers','extensions')，这将意味着生成的文档会包括这些目录(/var/html/app/protected/{models,components,controllers,extensions})下面的类，大家可以自己修改，比如把controllers目录加到这个数组，生成的文档也会包含controller的API。但是千万不要把 views 之类的目录也加进去，否则会报错。
类的名字要全局（应用层+框架层）范围唯一。原因是"yiic api"命令会通过include_once把涉及的源文件全部加载进，再通过reflection得到类的信息，如果有不同的类使用同样的类名，PHP会报错: "Cannot redeclare class XXX"。比如我就遇到因为多个modules的话就会有多个"DefaultController"类，没有办法把modules的API也记入文档，暂时不知道这个有什么好的解法没有。

新手，大家见笑。

#2 hightman

Junior Member

Group: Members
Posts: 43
Joined: 23-August 09

Posted 20 November 2010 - 09:14 AM

你这样改太麻烦了，而且修改了官方代码非常不好。
其实可以简单继承 ApiCommand 并覆盖部分方法即可，我之前有这样做过，但后来YII修改了一些路径的计算方式导致我的代码临时不能用了，暂时没时间也没去弄它了。

类似以下的方法去弄，尽量避免直接修改官方提供的代码以免导致不兼容或引起其它BUG。

Yii::import('application.commands.ApiCommand');
class YdocCommand extends ApiCommand
{
}

#3 robhsiao

Newbie

Group: Members
Posts: 7
Joined: 02-November 10

Posted 20 November 2010 - 09:50 AM

噢天啊，我大费周章，hightman几句话就搞定。佩服啊。是CU的hightman吗？

----------

更新：

测试了一下，如果想不改动原来的代码，貌似也不太好处理。
首先要继承ClassDoc，覆盖它的getSourceCode的方法；
然后又要继承ApiModel，覆盖它的processClass方法（虽然只是修改一句话，但是还是要把代码拷贝过来，而这一段代码比较复杂一些）；
然后再继承ApiCommand，覆盖renderSourceLink和buildModel。

This post has been edited by robhsiao: 20 November 2010 - 11:28 AM

#4 hightman

Junior Member

Group: Members
Posts: 43
Joined: 23-August 09

Posted 20 November 2010 - 10:18 PM

原先早点的版本没有显示源码功能，所以没问题只要继承一下ApiCommand就可以了，现在的问题在于：
ApiModel.php 中关于 basedoc 基类的定义：

在 loadSource() 时把路径中的 YII_PATH 清除，在 getSourceCode() 里的前头补上 YII_PATH。

以至于如果我的 sourcePath 并不在 YII_PATH 底下时就出错。。。。

稍后我再看看有没有什么更简单的方法解决这个问题，或者提交官方建议修正这个限制，当 sourcePath 不包含YII_PATH时也能支持一下。

#5 hightman

Junior Member

Group: Members
Posts: 43
Joined: 23-August 09

Posted 20 November 2010 - 11:35 PM

刚才尝试了一下，用了不是非常优雅的办法实现了。不改任何原有代码，只需将附件中的 YdocCommand.php 放入
$yii/build/commands/ 目录即可。

在 build/ 目录下的使用方式：

1. 针对某个开发好的YII app建立 API 文档
php build ydoc /path/to/doc_dir /path/to/app/protected

2. 针对某个文件建立API文档
php build ydoc /path/to/doc_dir /path/to/file

特别说明：
红色部分可以是任意文件或目录，请使用绝对路径，如果使用相对路径则默认会当作在 YII_PATH，比如
输入 framework/base 就相当于 YII_PATH/framework/base

自动描扫目录下的文件的时候会排除目录名为 views 或 view 的文件夹，同时排除命名没有以大写字母开头的 .php 文件。

此外，如果检测到生成DOC的目录是 protected 结尾，那么会自动把框架基础文件也加进去，避免一些无法识别的链接。

--手注：其实如果官方团队稍作修改，应该可以更完美的支持APP文档生成。