简单介绍下phpDocumentor
phpDocumentor 是非常强大的一个工具.强大到什么地步呢?或许可以说,见到的和php相关的文档,起码有50%(据我大概看到的情况所得,没有十分准确的数据)都是用他生成的吧.
一般我们会把注释写在代码里面,然后利用注释来生成文档.也就是从另外一个角度来讲,我们的文档是在代码,是在注释里面的.这样很方便就可以让代码和文档同步,不至于脱节.
1.安装
有两种安装方式:
a.pear
pear install phpdocumentor
至于什么是pear,请看下相关知识吧.
b.web形式
下载放到可以被访问的目录即可.
这个怎么用,我也没有弄太清楚.没有pear的好用.
2.生成帮助文件工程
D:\xampp\php>phpdoc -d "d:\wwwroot\YPHP\lib" -t "d:\wwwroot\YPHP\doc" -o "CHM:default:default"
需要注意的是,小心反斜线被当成了转义字符,所以用"/"来代替"\"还是比较好的.或者用"\\"
PS:我就因为这个问题,不得不去打开phpdoc的源代码去查是什么问题.因为对CLI这种形式的调用不是很熟悉,所以整整浪费了一个小时的时间才找到问题所在
3.编译
下载微软的Microsoft Help Workshop,打开编译即可.
或者命令行调用:
C:\Program Files (x86)\HTML Help Workshop>hhc d:\wwwroot\YPHP\doc\phpdoc.hhp
之所以在这里强调命令行,是因为命令行的形式更容易形成自动化.
4.参数
phpdoc –h
可以查看详细参数,这里无需赘述
phpdoc -d "d:\wwwroot\YPHP\lib" -t "d:\wwwroot\YPHP\doc" -o "HTML:Smarty:PHP" -i "*thirdpart*" -is on –ti "YPHP Framework Document"
我使用的一个参数,目标目录-d,输出目录-t,-o是输出HTML,-i忽略thirdpart, -ti标题
5.中文乱码与自定义模板
phpDocumentor采用的是西欧编码,所以对中文的注释支持不是很好.
我建议将原有的模板复制一份,然后使用和你项目一致的编码,另外一个好处就是,你可以对模板进行修改.来创建自定义的文档
phpDocumentor的相关的资源: