安装与使用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 计划中要进行的项目
http://manual.phpdoc.org