phpDocumentor PHP 文档生成 CHM

好久没写新东西了。

最近遇到很头疼的事，好多代码要维护，时间长了，自己写过的代码都想不起来。

要调用某个对象的方法，每次都要打开那个类定义的 PHP 文件，找到方法的定义部分，然后仔细看看参数列表才能想起来怎么用。

最麻烦的是，有时候想不起来那个方法是在哪个类里面定义的，必须得去代码根目录 grep ，然后等半天……

相对比的，我开发程序时，手边必备的几个文档：PHP手册、MySQL手册、HTML手册、CSS手册、Javascript手册，以及最近开始用的 ActionScript手册。这些都是 chm 版本的！

Chm 帮助文件有 2 个最大的好处，一个是索引，另一个是全文检索。

用索引可以一边输入，一边过滤掉不匹配的关键词，迅速定位到想要的那个函数名。

当不知道关键词是什么的时候，可以用 like 语句在 chm 文件里面的每一句话中匹配关键词。

原本，用 Zend Studio 也有代码提示和自动完成，不过这个用 Java 虚拟机运行的 IDE 实在是慢，受不了，也不习惯。

今天花了好长时间，研究 php 文档生成工具，找到了几个，主要都是生成 html 页面的，而且格式很难看，重要的是没有好用的索引，更没有全文搜索，没意思。

PhpDocumentor 支持 chm 生成，这个让我眼前一亮！

简单看了下官方文档，然后就下载了 zip 格式的压缩包，就是这个压缩包，浪费了我好长时间去调试错误！！

设定好 php 源码路径，再设置文档格式，选择 chm，输出了一堆文件，包含 hhc，hhp 等，这些是 chm 的“源码”，需要用 Windows 自带的 HTML Help WorkShop 进行编译，然后才能生成 chm。

而那个 zip 压缩包，居然是有严重 bug 的版本，生成的 hhc 文件，里面有一行错误代码，提示 contents.hhc.tpl 找不到！！！

最开始我没有意识到问题在这里，只是用 WorkShop 反复编译那堆 hhc 文件，总是不成功！我都有放弃的念头了。

后来仔细看错误提示，好像是 hhc 文件的问题，打开一看，才知道是上述原因。

再去 phpDocument 源码里面找 contents.hhc.tpl，真的没有！不过，却有 contents.hhc.tp 这个文件！！！

然后列了下目录，几十个文件，大部分都是 tpl 扩展名，而有几个文件是 tp！！！

靠！什么玩意儿，是程序员马虎了还是打包工具的问题？

重新下了个 tgz 版本的 phpDocument，问题全无，chm 编译顺利！

另外，默认编译的 chm 是不带搜索（全文检索）功能的，更改方式如下：

打开一个项目文件，单击“Project（项目）”选项卡的“Change project options（改变项目选项）”，在“Options（选项）”对话框的“Compiler（编译）”选项卡中选中“Compile Full Text Search Information（编译全文搜索信息）”即可。

附赠命令行范例：

$> php phpdoc -o CHM:default:default -d ../lib/ -t ../docs/ > ../php_doc.log

Tags: phpDocumentor