将开发人员与文档的关系比喻为油和水颇为贴切——因为它们都互不相溶。很多开发人员都认为编写文档是一个浪费时间的苦差使。所以，很不奇怪地看到，很多公司都雇用独立的人员来编写技术文档，而不是说服开发人员和程序员自已编写文档。
但是对于以PHP开发方式，phpDocumentor是一种解决以上问题的方法。与Java的javadoc工具类似，phpDocumentor能够通过嵌入在PHP代码中的特定标识符和注解自动生成API文档。由于绝大多数的开发人员通常都在代码中以各种方式使用到注解，所以利用这一工具可以最大限度地降低他们的负担。而且，phpDocumentor可以以不同的格式(包括HTML，XML和PDF)输出文档，由此进一步地减少了人工文档化的时间。当然，对于更为专业化的文档，比如用户手册或者程序流框图，你仍然需要懂得技术的人来编写。但是对于比较简单的文档和方法原型，phpDocumentor已经是一款胜任的工具。
在这一速成阶段中，我将开始告诉大家在标记你的代码时如何使用特定标识符和语法。同样，我也会告诉大家使用phpDocumentor来读取你的代码并自动生成一个类树和method/property信息的基本用法。
一个完整的解决方案
作为“PHP的完整文档化方案”，phpDocumentor以读取源代码的注解并使用这些注解建立一个专业化的简洁的API文档。这一工具支持不同的输出格式：HTML，PDF，Windows HLP，以及XML。在每一这些输出格式中，可以使用到不同的模板和设计风格。并且你甚至可以建立你自己的模板——phpDocumentor使用这一著名的Smarty template(聪明模板)引擎来操作数据。
PhpDocumentor可以通过PEAR获得，PHP Extension 以及 Application Repository可以从Phpdoc.org中下载。为了安装，在你当前的PEAR目录中解压缩下载的文件，并将工具浏览器指向phpdoc.php，你就可以看到如图A所示的图形。
图A. PhpDocumentor的主Web界面
这一窗体是PhpDocumentor的主Web界面(当然还有一个命令行界面，但我们集中在GUI界面)，你可以使用这一界面告诉程序需要读入哪些PHP类并生成些类的文档。现在，让我告诉你如何使用PhpDocumentor语法来标记你的代码。
