使用 PHPDocumentor 建立源程序文档

    有句话说：软件 = 代码 + 文档。可见文档的重要性！尤其在大中型项目和（或）团队协作编码的情况下，文档显得尤为重要。人员交接、团队交流，只有代码、没有文档是难以想象的。即使是一个人编码，天长日久，自己阅读自己曾经的代码也是一件耗时和费神的事情。

    然而，整理和编制文档却是一件枯燥和乏味的事情，尤其是项目工期紧张的时候，最早做出让步和牺牲一定是编制文档的工夫。

    幸好有一些文档辅助编写工具，可以帮我们的大忙，PHPDocumentor 就是很好的文档编制辅助工具。

    PHPDocumentor 最早是从 JAVADoc 借鉴和移植到 PHP 环境下的，现在已经成为一个优秀的文档辅助工具之一。

    PHPDocumentor 以 PEAR 扩展类库的形式分发，需要通过 PEAR 管理工具来下载和安装。

    安装命令为：

    pear install --alldeps PHPDocumentor

    参数 --alldeps 表示同时下载安装 PHPDocumentor 依赖的其它 PEAR 类库。

    PHPDocumentor 的使用：

    编写代码时，需要在 PHP 文件、类、成员变量、成员函数等部位，以约定的格式(很重要！)，进行代码注释。PHPDocumentor 可以根据代码的语法特征和约定的注释格式，生成最终的文档。文档以 Html 的形式保存，利于在网上发布和浏览。

    文档的一般注释格式为：

    标识文件：

    /**

     * @licens ……

     * @package ……

     * 【这里是注释……】

     * @author ……

     * @copyright

     */

    标识成员变量：

    /**

     * 【这里是注释……】

     * @var string/int/array

     */

    标识成员函数：

    /**

     * 【这里是注释……】

     * @param ……

     * @return ……

     * @author ……

     * @copyright

     */

    生成文档的 DOS/Shell 命令为：

    phpdoc -d <包含代码的文件夹> -t <保存生成文档的文件夹>

    这个命令很灵活，还有其它一些参数用于生成不同详细程度的文档。

    作者：张庆(网眼) 西安 PHP 教育培训中心 2010-7-6

    来自“网眼视界”：http://blog.why100000.com

    作者微博：http://t.qq.com/zhangking

    “十万个为什么”电脑学习网：http://www.why100000.com