写文件是一个程序设计师最最痛苦的事情之一，尤其是写了一堆程序后有人要你把 Function ，Class 等等等等，写成一份文件。

这事情不管你是写 c/c++ , perl , ruby , php 都不例外。

phpDocumentor 是我们的救星! 只要在写程序的时候，乖乖的写一点注解，写一点范例，多一点说明，注意一下格式，等到程序完工后，只要一个指令，就可以立刻把全部程序的说明文件产生出来，而且还有多种样式可以选择，甚至可以作成 PDF , CHM 喔…

好了，屁话不多说，先来说说怎么装上这好用的东西吧… phpDocumentor 本身已经是 pear 的成员之一，所以安装的时候只要用 pear 来安装即可（以下范例为在 Windows 下进行，以后再补上 LInux 下的）

–如果你已经有装 php 跟 pear 请跳过–

首先假设我把我的的 php 安装路径在 d:php 也就是说我从 www.php.net 下载了最新的 php win32 安装档案，解开后放在 d:php 那么这个目录下面应该有 d:phpPEAR这个目录，但是当你进去看的时候，你会发现好像没有 PEAR 相关程序库阿… 没错，这个时候你还没有安装 PEAR 请先用 go-pear.php 安装基本 pear 环境。

那么在 d:php 目录下有一个档案，叫做 go-pear.bat 请开一个 cmd 视窗去执行他，中间会有一些问题，基本上都照预设值去跑就可以了…

跑玩后，你的 pear 应该会被安装在 d:phpPEARpear 下面，而帮助你安装其他 pear 套件的 pear.bat 则在 d:phpPEAR下面

–安使安装 phpDocumentor –

安装 phpDocumentor 的过程也很简单，只要利用 pear.bat 即可！ 使用指令如下

d:phpPEARpear.bat install -o PhpDocumentor

当中有多下一个 -o 的参数，意思是要 pear 把相依的套件也一起下载安装。 安装完成后 d:phpPEAR 下面应该会多一个 phpdoc.bat 的批次档，我们就可以用这个批次档来产生我们的文件。

– 使用 phpdoc.bat 产生文件 –

产生文件的方式我通常只有用下面一行指令解决：

d:phpPEARphpdoc.bat -o HTML:Smarty:PHP -d d:myProjectphp_source -t d:myProjectdocs

这样子的意思是说，采用 HTML:Smarty:PHP 的样板格式，然后原始码目录在 d:myProjectphp_source ，接着把产生的文件放在 d:myProjectdocs 底下。

当中若是你只要对一个档案作文件的话，可以把 -d 改成 -f 然后后面接的着就是指定的档名。

样板的格式基本上有 HTML, XML, PDF, CHM 四大类别，通常我用的都是 HTML:Smarty:PHP 这个，因为他比较好看!

另外还有就是 CHM:default:default 这个.用来产生 chm 的，不过他产生出来的是 .hhp 档案，也就是还没有经过 HTML helper 编译过的档案，所以要另外安装 HTML Helper 来编译 hhp 档案就可以产生你要的档案。

– 最后来说一下怎么写注解 –

phpDocumentor 的注解有一定的规格，但是都跟我们原来写注解的方式很像，只是要注意一下东西而已。 简单的来看个范例好了

最后修改于 2008-11-23