直到几年前，基本上可以使用两种工具在PHP中生成API文档：phpDocumentor和Doxygen。phpDocumentor长期以来一直被认为是标准，当需要更高级的功能（如继承图）时，Doxygen会引起注意。然而，此时phpDocumentor实际上不受支持（尽管一小群开发人员正在开发新版本），并且Doxygen从未将PHP作为其主要关注点。因此，许多新项目开始作为替代品出现。
其中之一是DocBlox。我很清楚还有其他几个-事实上，我已经尝试过其中的几个。这篇文章不是要讨论这个或其他解决方案的优缺点；目的是向您介绍DocBlox，以便您可以自己对其进行评估。
获取DocBlox
DocBlox可以通过多种方式安装：
- 您可以通过GitHub签出该项目。
- 您可以下载快照。
- 您可以下载版本。
- 您可以使用使用PEAR安装程序。
我个人更喜欢使用PEAR安装程序，因为它非常简单：
$ pear channel-discover pear.michelf.com $ pear channel-discover pear.docblox-project.org $ pear install -a docblox/DocBlox-beta
第一个channel-discover是抓取渲染过程中可选用的第三方包，将描述中的Markdown转成HTML。并且不要让“测试版”状态欺骗了您——这个项目在这一点上非常稳定；作者MikevanRiel在完善功能时只是比较保守。
如果您通过Git或快照检出项目，您只需要展开存档并记下它的位置——我过去使用这种方法时，通常会创建一个指向的符号链接bin/docblox.phpmypath中的脚本：
$ ln -s path/to/docblox/bin/docblox.php ~/bin/docblox
使用DocBlox
安装DocBlox后，如何使用它？这真的很简单：
$ cd some/project/of/yours/ $ mkdir -p documentation/api/ $ docblox run -d path/to/source/ -t documentation/api/
此时，DocBlox将愉快地扫描位于path/to/source中的源代码，并在documentation/api中使用其默认HTML模板为您构建API文档。完成后，您可以将浏览器指向documentation/api/index.html并开始浏览您的API文档。
使用DocBlox识别丢失的文档块
在运行时，您可能会在输出流中看到一些通知，例如：
2011-08-02T16:08:34-05:00 ERR (3): No DocBlock was found for Property $request in file Mvc/Route/RegexRoute.php on line 16
此输出对于识别您在代码中省略文档块的位置非常有用。您可以使用tee非常轻松地捕获此信息：
$ docblox run -d path/to/source/ -t documentation/api/ 2>&1 | tee -a docblox.log
我建议在运行DocBlox时执行此操作，检查输出并在遇到这些错误时添加文档块。
（您可以使用诸如PHP_CodeSniffer之类的工具执行类似的操作。不过，更多的工具从来都不是坏事。）
但是，如果你想禁用冗长，你可以通过传递-q或--quiet选项。
类图
默认情况下，DocBlox将尝试生成类图。为此，您需要在路径的某处安装GraphViz。然而，结果非常棒——您可以放大和缩小图表，然后单击类以访问相关的API文档。
（类图通常从每个页面的顶部开始链接。）
指定备用标题
默认情况下，DocBlox使用自己的徽标和名称作为文档的标题，并出现在输出的“标题”行中。您可以使用--title开关更改它：
$ docblox run -d path/to/source/ -t documentation/api/ --title "My Awesome API Docs"
使用备用模板
虽然DocBlox的默认模板是合理的，但对我来说它最初的卖点之一是您可以想象地创建新模板。为了对此进行测试并解决一些问题，Mike为一些PHPOSS项目编写了模板，包括ZendFramework和Agavi。模板需要位于DocBlox可以找到它们的位置—在DocBlox/data/themes在你的PEAR安装下，或者简单地data/themes如果你安装了一个发布tarball。调用主题就像使用--template参数一样简单：
$ docblox run -d path/to/source/ -t documentation/api/ --title "My Awesome API Docs" --template zend
尝试每个提供的主题，看看您最喜欢哪个——也许您可以尝试编写一个主题。每个给定的主题只是一个XML文件和一小组XSL样式表，以及可选的CSS和图像以与生成的标记一起使用。
迭代文档
当您生成文档时，DocBlox实际上会创建一个SQLite数据库，用于存储它在解析您的代码库时了解到的信息。这使得它在解析时（它可以在完成对类或文件的分析后从内存中释放信息）以及在转换为输出时（因为它可以迭代地查询数据库的结构）都非常非常快。
这对你意味着什么？
好吧，首先，如果您想尝试新模板，它不需要重新解析您的源代码——它只是从已经解析的定义中生成新的输出。这在创建新模板时非常有用。对于小型项目，生成通常是即时的。
其次，这意味着您可以一次构建完整的文档，并且只定期更新它（您可以使用--force选项来完成）。这对于构建过程特别有用。
配置
任何丰富的CLI工具的一个问题是您经常会得到大量的选项，并且在调用之间记住它们可能很难（特别是如果您只在发布期间运行该工具）。DocBlox允许您在项目中创建配置文件docblox.xml。格式比较简单；（大部分）等同于我使用的上述选项如下：
<?xml version="1.0" encoding="UTF-8" ?>
<docblox>
<parser>
<target>documentation/api</target>
</parser>
<transformer>
<target>documentation/api</target>
</transformer>
<files>
<directory>path/to/source</directory>
</files>
<transformations>
<template>
<name>zend</name>
</template>
</transformations>
</docblox>
您不能在配置中指定标题，但无论如何这通常都是模板驱动的。
DocBlox然后将在当前目录中查找此文件并简单地使用它，允许您按如下方式调用它：
$ docblox run
或者你可以自己指定配置文件：
$ docblox run -c config.xml
（旁注：在我撰写本文时的最新版本0.12.2中，我未能成功指定模板名称。）
搜索
如果仔细查看生成的输出，您会注意到一个搜索框。默认情况下，这是行不通的……因为它指向一个PHP脚本！但是，当安装在能够为PHP提供服务的服务器上时，它可用于帮助查找类、方法等。例如，您可以搜索ZendFramework1.11API文档。
结论
希望本教程能让您开始研究DocBlox。到目前为止，我对这个项目的所见所闻感到非常满意，并很乐意推荐它。但是，还有其他选择，我也建议您尝试一下；Liip最近发布了一个功能比较，那篇文章可以用作您自己调查的起点。
（披露我在MikevanRiel开发DocBlox时贡献了一些补丁和一些建议）。
