PhpDocument生成帮助文档使用说明

  最近做一个比较大的项目，要求我们写很多的文档，以前就听说过这个东西，但是一直没用。文档太多要写需要花费很长时间，想起来用这个东西来生成文档，今天试了试效果很不错，主要是开发过程中一定要写规范的注释。

       对于一个大型的网站来说，文档往往决定着项目的成败，文档在开发的过程中能够给我们提供很好的帮助。如果我们的团队中来了一些新的成员，原来的成员向新人很好地介绍了这个复杂的系统的架构，接着就让他们开始工作。这个时候如果没有文档，他们可能需要很长时间才能去读懂代码和整个项目的结构。

          phpDocumentor是用PHP写的一个工具，被设计用于直接从PHP代码和外部文档中创建完整的文档。事实上，PHP源代码是如此容易理解，它实际上就是自己的文档。phpDocumentor进一步揭示了这一点，它把从PHP中找到的所有逻辑结构，例如文件、类、函数、定义常量、全局变量和类变量/方法，解析出来并把它们组织为传统的手册格式。此外，在最新版本1.3.0中，PHP5中引入的源代码要素(类常量、接口和其它东西)也能够被解析了，这个功能要求phpDocumentor是通过PHP5运行的。输出的结果可以用于远程Web浏览、打印和集成到IDE帮助系统(通过HTML、PDF和CHM的转换器)。

          官方提供了两种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界面还是命令行界面

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

       使用pear命令安装

       首先要安装pear，如何安装请参考我的另一篇文章http://hi.baidu.com/1024114660/blog/item/401b745059423b0e367abe11.html

        pear upgrade  PhpDocumentor  该命令将访问http://pear.php.net/并在系统上自动安装或升级PhpDocumentor。如果你在线安装总是失败你也可以手动下载tgz文件然后用pear install PhpDocumentor-1.4.3.tgz。你也可以解压缩存档文件，然后直接在解压缩得到的目录中使用phpDocumentor。命令接口由phpdoc文件处理。你需要目录放到包含路径中。

tar -xzvf PhpDocumentor-1.4.3.tgz

cd PhpDocumentor-1.4.3

chmod 755 phpdoc

./phpdoc -h

windows手动安装包的下载地址http://sourceforge.net/projects/phpdocu/files/

具体的使用方法如果用的是wen模式，界面上相应的提示，使用非常方便。如果用的是命令行模式，可以使用phpdoc -h得到帮助

注：代码注释的风格我们可以参考ZF框架，也可以去phpDocumentor官方网站查看ags说明手册，里边有详细的说明

1. 配置 phpdoc.bat 使其指向您所安装php的位置；

打开phpdoc.bat 进行编辑 更改phpCli，即SET phpCli=F:\server\program\php524\php.exe  

此时表示 我安装的php执行文件在F:\server\program\php524\的位置。最后让PhpDocument运行于php环境中。

2. 执行 phpdoc.bat 选择  PhpDocument

3. PhpDocument生成帮助文档操作
PhpDocument生成帮助文档有两种形式即 命令行和web页面，在这里我主要讲解web页面，在php环境中运行PhpDocument程序，即执行程序浏览PhpDocument下的index.html，进入PhpDocument生成帮助文档操作界面，其中生成文档的主要栏目是Files Output Option

下面我们来详细介绍一下生成的步骤

(1) 点击 Files栏目按钮 加入需要生成帮助文档的php程序

 

   

   （2）点击Output栏目按钮选择保存位置和生成样式

（3）点击Options栏目按钮选择保存位置和生成样式

多选框处可根据自己需要选择这里不过的说明。

（4）选择Working Directory  的路径，然后点击 create按钮开始生成帮助文档 当程序出现Operation Completed!！表示操作完成

注意：以上是最基本的采用PhpDocument生成帮助文档的步骤操作希望给你的学习带来帮助。Kphp爱好者提供，如有转载或是使用图片请标注来自kphp开源框架，网址：http://www.kphp.org/?dguide-show-7.html。以上截图操作步骤为phpDocumentor v1.4.3 Web Interface 版本

[选择要生成文档的php项目文件夹时，里面尽量不要含有非PHP格式文件（如：CSS,JPG,HTML等），刚开始的时候生成不成功可能就是这个原因。]

例如错误：

Warning:  preg_replace() [function.preg-replace]: No ending delimiter '|' found in E:\php\PHPnow\htdocs\default\pd\phpDocumentor\Setup.inc.php on line 691

Fatal error:  Call to a member function getImplements() on a non-object in E:\php\PHPnow\htdocs\default\pd\phpDocumentor\Converters\HTML\Smarty\HTMLSmartyConverter.inc on line 1401