phpDocumentor

phpDocumentor，是一个用PHP写的工具，对于有规范注释的php程序，它能够快速生成具有相互参照,索引等功能的API文档。老的版本是 phpdoc，从1.3.0开始，更名为phpDocumentor，新的版本加上了对php5语法的支持，同时，可以通过在客户端浏览器上操作生成文档，文档可以转换为PDF,HTML,CHM几种形式。

通过读取名为文档块(DocBlocks)的特殊的PHP注释，phpDocumentor生成手册格式的文档。文档块是软件项目的作者应该为有用信息作注释的地方，它能够被其他人使用(未来你自己也可能用到)，以确定如何使用和扩展你的PHP包。

尽管在源代码中添加简洁文档的能力是基本的，但它不能代替源代码之外的详细文档的重要性，例如用户手册或你正在阅读的这个指南。如果你现在阅读的这些文本是放在源代码中供phpDocumentor使用的，那它的实用性就会变得很小，因为这不仅使代码显得混乱，而且文本本身也很难查找。然而，在源代码中的文档和外部文档之间创建超链接的能力是基本的。函数foo的外部文档必须能够参考代码中生成的文档，有了phpDocumentor这一切终于成为可能。

phpDocumentor工作流程

PHPDocumentor工作时，会扫描指定目录下面的php源代码，扫描其中的关键字，截取需要分析的注释，然后分析注释中的专用的tag，生成 xml文件，接着根据已经分析完的类和模块的信息，建立相应的索引，生成xml文件，对于生成的xml文件，使用定制的模板输出为指定格式的文件。

phpDocumentor安装

官方提供了两种phpDocumentor的安装方法。第一种方法是从pear.php.net和sourceforge.net下载和解压缩任一可用的档案，另一种方法是通过PEAR安装工具安装。已有一个名为“Phing任务”的计划，准备通过其它新的有前途的安装框架来分发，例如ZZ/OS安装工具。然而，phpDocumentor的开发者只为上述两种官方的安装方法提供支持。

• 从Pear.Php.net或Sourceforge.net下载

在从pear.php.net或sourdeforge.net下载.zip或tar包来安装phpDocumentor之前，请先确认你要使用 phpDocumentor的Web界面还是命令行界面(参考“phpDocumentor工具的基本用法”一节来帮助你做这个决定)。

如果想要使用命令行界面，把文档解压到任意一个目录，比如/home/myuser/phpdoc或C:\Program Files\phpdoc，然后把目录添加到你的path语句。运行“phpdoc”命令来使用它。在Windows中，你需要编辑phpdoc.bat 文件，把第一行改为PHP的CLI版本的路径(默认情况下通常是C:\php4\cli\php.exe)。

如果想要使用Web界面，你必须安装Web服务器，例如Apache，这个Web服务器必须有能工作的PHP sapi。为了测试这一点，把下面的代码([code]和[/code]之间的内容)保存为phpinfo.php，把这个文件放到Web服务器的根目录下，浏览http://localhost/phpinfo.php。

phpinfo.php:
[code]
       <?php
       phpinfo();
       ?>
[/code]

如果你看到漂亮的PHP信息显示出来，那么你的PHP安装就是能工作的。要使用phpDocumentor的Web界面，只要简单地把档案解压缩到Web 服务器根目录的一个子目录(例如phpdoc)，然后浏览那个位置(http://localhost/phpdoc)。

要观看更新的Web界面，需要一个支持Javascript的浏览器，例如Netscape、Mozilla、Internet Explorer、Opera或Konqueror。如果你想要使用不支持Javascript的浏览器，例如links/lynx，请使用旧的Web界面，phpdoc.php，它位于http://localhost/phpdoc/phpdoc.php。

• 从PEAR安装

要从PEAR安装phpDocumentor，你首先必须有一个能够工作的安装好的PEAR。关于正确安装PEAR的操作指南位于PEAR的官方网站(http://pear.php.net)。phpDocumentor的开发者不对PEAR的安装问题提供支持，作为替代的，请从PEAR的开发者那里寻求帮助。

安装命令行的phpDocumentor非常简单，运行：

$ pear install PhpDocumentor

然后你就可以完全访问phpdoc命令了，不管是在Windows下还是Linux下，不需要进一步配置。

安装使用Web界面的phpDocumentor，首先你必须修改PEAR的配置变量data_dir，把它指向你的Web服务器根目录的一个子目录。完成这项工作的最简单的办法是通过PEAR的命令行界面运行：

 $ pear config-set data_dir /path/to/document_root/pear

从Web界面来配置这个值也很简单。单击左边帧里的配置图标，在data_dir文本框中键入地址。(这个Web界面的入口在哪里我也没有搞清楚，不过从命令行配置确实是一个好办法)

一旦配置完成，使用上面第二段中的命令就可以简单地安装phpDocumentor，然后你可以浏览http://localhost/pear/PhpDocumentor来访问Web界面。一旦这步配置完成，就无须再做改变，通过使用pear的upgrade命令你可以毫不费力地升级到未来的 phpDocumentor版本。

phpDocumentor相关资源

官方网站 ｜ 最新官方下载

相关条目

• PHP

参考来源