开发人员和文档就像油和水——他们之间不能很好地溶合。很多开发人员发现编写文档非常枯燥，非常浪费时间。所以就不奇怪为什么有很多公司雇请单独的人员来创建技术文档，而不试图劝服开发人员和程序员自己写文档。
但是如果你是用 PHP 进行开发的话，就有一个叫做phpDocumentor 的方案可以使用。与 Java 的javadoc 工具类似，phpDocumentor 通过读取内嵌在 PHP 代码中的标识符和特殊注释自动创建 API 文档。因为大多数开发人员无论如何都有在代码中写注释的惯例，所以使用这个工具对他们带来的负担是最小的。而且phpDocumentor 可以以很多种格式输出文档（包括 HTML、XML 和 PDF），这样更进一步减少了浪费在手工编制文档上的时间。当然对于用户手册和处理流程图之类的复杂文档，你依然还需要技术写手。但是，对于简单的类文档和方法原型，phpDocumentor 是一个非常合适的工具。
在本次课程里，我首先向你展示在编写脚本时可以使用的特殊标识符和语法。然后我还会向你展示使用phpDocumentor 读取代码和自动生成类树和方法/属性信息的基础知识。
完整的解决方案
标榜为“用于 PHP 的完整的文档解决方案”，phpDocumentor 能够读取源代码中的注释，然后使用这些注释创建专业的、格式整洁的 API 文档。它支持很多种输出格式，包括 HTML、PDF、Windows HLP 和 XML。每种输出格式提供了不同的模板和设计。甚至你还可以创建自己的模板——phpDocumentor 使用著名的Smarty 模板引擎呈现数据。
phpDocumentor 是通过 PEAR 提供的，所谓 PEAR 是指 PHP 扩展和应用程序知识库（PHP Extension and Application Repository），可以在Phpdoc.org 下载这个工具。安装过程很简单，只要将下载的压缩文件解压到你的 PEAR 本地安装并把浏览器指向安装目录中的phpdoc.php脚本即可。你应该可以看到类似图A的画面。
这个表单（form）是phpDocumentor 的基本 Web 界面（另外还有一个命令行界面，但是我们这里只讲 GUI），你将使用这个界面告诉应用程序读取哪些 PHP 类并为它们生成文档。后面我们会详细讲到——首先，我将展示如何使用phpDocumentor 语法标记代码。
