PHP文档工具,PHPDocumentor续 PHPDocumentor

leakon

PHP文档工具,PHPDocumentor续

关于PHPDocumentor,我在05年的PHP&More杂志第二期中介绍过其基本用法.没想到给它写续篇时,已经是四年之后.

这么多年过去了,PHPDocumentor依然是PHP文档工具里的不二选择,虽然版本进化不大,不过更新却一直在进行.

去年8月,PHP4已经退出历史舞台,很多标记,如@abstract,@public已经可以直接从代码中获取,需要手工声明的地方也越来越少了.

本篇重点补充之前文章没有详细讲的几个细节问题:

• 如何区分文件和class的DocBlock
• 如何将演示代码写入注释
• 如何生成中文文档
• 如何编译CHM文件

如何区分文件和class的DocBlock

PHPDocumentor生成的文档通常通过两个维度进行索引,一个是文件列表,一个class tree.

文件列表的注释内容依赖于File DocBlock;而Class的注释内容则依赖于Class DocBlock.

如果一个文件里边只有一个class,那么写在class之前的DocBlock就会让PHPDoc犯晕,这个Doc到底是File的还是Class的呢?

所以,为了避免PHPDoc抛出warning,我们最好在文档最上边和Class最前边分别加上DocBlock.这样就OK了.

另外需要注意,只有包含了@package的注释块才会被认为是文件级别或者Class级别的DocBlock.

如何将演示代码写入注释

我们在使用别人的代码的时候,最需要的就是示范代码,不用细细的去看清每一个函数的用法,只要照猫画虎就能用.

同样的,在我们写代码的时候,最好也把这些快速上手的演示代码写到文档里边.

PHPDocumentor提供了两种方式整合示范代码.一种是@example标记;一种是code标签.

@example标记

在注释块中,写上@example 标记,后边跟上演示代码的文件路径,PHPDocumentor会自己为对应的代码生成一个页面,并进行语法高亮.

/*
* @example ../example/code/mysql.class.php
*/

Code标签

Code标签则需要直接写到注释块中间,我更趋向于Code标签,因为这种方式下,代码和注释是一体的,都在同一个文件里边,当代码产生变动时,注释更容易得到更新.

/*
* <code>

* phpinfo();

* </code>

* @author Easy

*/

特别需要注意的是,Code标签需要写到各种@标记之前,否则将不会生效.

如何生成中文文档

虽然大家的英文可能非常好,但是出于团队协作的便利,在书写文档时,我还是建议大家尽可能采用中文.

PHPDocumentor在生成中文页面时,会产生乱码问题.这主要是因为它的模板里边默认的字符集是ISO-8859-1的.只需要修改对应的字符集为GBK或者UTF-8,就能在生成的文档中正确显示中文了.

PHPDocumentor采用Smarty作为模板,所有的模板都放置在PHPDocumentor/Converters/下,修改对应的文件即可.如采用的是默认的html模板,其模板文件在

phpDocumentor/Converters/HTMLframes/templates/default/templates

下,修改其中的head.tpl、index.tpl、blank.tpl、top_frame.tpl文件的charset为GBK/UTF-8即可.

如何编译CHM文件

要编译生成CHM文件,首先需要在PHPDocumentor的Output中,选择CHM的模板.这样PHPDocumentor按照CHM文件的规范为我们组织文件.在输出的目录根下有一个phpdoc.hhp文件

然后我们需要HTML Help Workshop(点这里下载).CHM的编译非常简单,将phpdoc.hhp拖拽到解压后的hhc.exe文件上即可.

另外,PHPDocumentor生成的目录是同时包含文件列表和Class列表的,读起来反而让人觉得重复,一般我会去掉其中的文件列表部分.要想在CHM中去掉这一部分,在输出目录的根下有一个content.hhp文件,包含了目录的各级列表,采用的是UL和LI标签来表达的,把你不需要的部分删除,重新编译就可以得到一份清晰易读的CHM文件了.