安装与使用PhpDocumentor

写文件是一个程序设计师最最痛苦的事情之一，尤其是写了一堆程序后有人要你把 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:\php\PEAR这个目录，但是当你进去看的时候，你会发现好像没有 PEAR 相关程序库阿...

没错，这个时候你还没有安装 PEAR 请先用 go-pear.php 安装基本 pear 环境。

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

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

--安使安装 phpDocumentor --

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

使用指令如下

d:\php\PEAR\pear.bat install -o PhpDocumentor

当中有多下一个 -o 的参数，意思是要 pear 把相依的套件也一起下载安装。

安装完成后 d:\php\PEAR 下面应该会多一个 phpdoc.bat 的批次档，我们就可以用这个批次档来产生我们的文件。

-- 使用 phpdoc.bat 产生文件 --

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

d:\php\PEAR\phpdoc.bat -o HTML:Smarty:PHP -d d:\myProject\php_source\ -t d:\myProject\docs

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

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

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

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

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

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

简单的来看个范例好了

<?php

/**

* 这里是这个物件的说明

* 可以多行喔!~

*

*/

class MyClass {

   /**

   * 这里是变量的说明

   *

   * @var int

   */

   var $a ;

   /**

   * 这里是变量的说明.

   *

   * @var string 这里也可以放说明

   */

   var $b ;

   

   /**

   * 这是针对函式的说明

   * 也是一样可以多行

   * 若是简单的范例也可以放这里

   *

   * @param int $a 可以放入传入的型态

   * @return array 可以说明回传的型态

   */

   function first ( $a ) {

      return array();

   }

}

?>

基本上都是在

/**

*

*/

中间写注解，别忘了每行前面要有个 * 喔!

注解比较常用到参数的应该是

@author 程序作者名称，联络方式

@const 常数

@deprecate 不建议使用的 API

@global 全域变量

@param 函数的参数

@return 回传值

@see 可参考函数

@since 开始时间

@static 静态变量

@var 物件成员变量

@todo 计划中要进行的项目