当我们编写了一套API供他人调用后，我们就会面临文档和沟通的问题，譬如：

1，文档格式不一，PDF、DOC、HTML各式各样。

2，文档与代码不一致，更新代码后忘记更新文档的情况频繁出现。

3，文档内容不清晰，难以学习和理解。

4，编写文档耗时费力，懒得写。

这时候就应该考虑自动化文档生成工具了。

phpDocumentor 是一套根据PHP代码注释自动生成文档的工具，其本身也是用PHP语言编写的，可以使用Pear来安装，也可以下载Phar包直接执行。

用于生成文档的代码注释叫做 DocBlock，主要由Summary，Description，Tags三部分组成，非常清晰易懂，写完DocBlock后，不仅程序注释补全了，还可以自动生成文档，一举两得，何乐而不为呢？

下面举例说明DocBlock的写法：

<?php
/**
 * Created by PhpStorm.
 * User: 孟光
 * Date: 14-3-27
 * Time: 下午2:19
 */

/**
 * Class Calc 这是一个简单的计算器。
 *
 * 这个计算器实现了基本的加减乘除运算方法。
 * 此程序的主要目的是为了演示PHPDoc的使用方法。
 * @version 1.0.1
 * @author 孟光
 */
class Calc
{

    /**
     * 计算器的版本号。
     * @var string
     */
    private $version = "1.0.1";

    /**
    * 计算器的最终计算结果。
    * @var float
    */
    private $result = 0.0;

    /**
     * 加法计算。
     * @param float $a 加数
     * @param float $b 加数
     */
    public function add($a, $b)
    {
        $this->result = $a + $b;
    }

    /**
     * 减法计算。
     * @param float $a 被减数
     * @param float $b 减数
     */
    public function sub($a, $b)
    {
        $this->result = $a - $b;
    }

    /**
     * 乘法计算。
     * @param float $a  乘数
     * @param float $b  乘数
     */
    public function multiply($a, $b)
    {
        $this->result = $a * $b;
    }

    /**
     * 除法计算
     * @param float $a  被除数
     * @param float $b  除数
     */
    public function division($a, $b)
    {
        $this->result = $a / $b;
    }

    /**
     * 获取最终计算结果。
     * @return float 最终计算结果。
     */
    public function getResult()
    {
        return $this->result;
    }

    /**
     * 获取计算器的版本号。
     * @return string 计算器的版本号
     */
    public function getVersion(){
        return $this->version;
    }
} 

然后我们使用phpDocumentor来生成文档：

#php phpDocumentor.phar -f Calc.php -d doc/api/

其中 -f 指定源码，-d指定文档输出目录。

然后我们就可以打开文档目录浏览文档了，默认的Clean模板使用了Twitter Bootstrap，风格清新，如下：

参考资料：

http://www.phpdoc.org/

http://www.phpdoc.org/docs/latest/index.html