phpDocumentor简明教程

 

phpDocumentor新手指南

目录

    phpDocumentor是什么？它能做什么？
    安装
      从Pear.Php.net或Sourceforge.net下载
      从PEAR安装
    如何为代码写文档才能被phpDocumentor使用
      以注释 的方式为PHP源代码写文档
         为全局变量写文档
         页面级的文档块(DocBlock)警告
      写外部文档并链接到源代码文档
    phpDocumentor工具的基本 用法
      命令行工具：phpdoc
      phpDocumentor的Web界面：docbuilder
    源代码
      sample1.php的源代码
      sample2.php的源代码
      sample3.php的源代码


正文

phpDocumentor是什么？它能做什么？

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

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

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


安装

    官方提供了两种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。为了测试这一点，把下面的代码(

和

复制代码

之间的内容)保存为phpinfo.php，把这个文件放到Web服务器的根目录下，浏览http://localhost/phpinfo.php。

phpinfo.php:

   <?php    phpinfo();    ?>

复制代码

如果你看到漂亮的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使用

    为你的代码项目写文档在大部分情况下都是简单的和直觉的。在你开始之前，你可能想要下载样本文档项目，一边阅读本文一边试着运行phpDocumentor，你可以使用sample1.php的源代码、sample2.php的源代码、sample3.php的源代码或phpDocumentor的tutorials/目录下的文件包。在解析之前，把例子拷贝到另外一个目录。

    首先，对空白文件sample1.php运行phpDocumentor。如果你使用命令行界面，在tutorials/sample目录下运行这个命令：
    $ phpdoc -o HTML:frames:earthli -f sample1.php -t docs

    如果你使用Web界面，点击“文件”标签，键入tutorials/sample/sample1.php的完整路径。然后点击“输出”标签，键入tutorials/sample/docs的完整路径，最后点击右下角的“创建”按钮。

    用Web浏览器打开新创建的tutorials/sample/docs/index.html文件，你将看到丰富的信息阵列，即便是没有任何文档注释的源代码，phpDocumentor也能够解析。继承信息、 多态性和常量都被自动识别出来了。请注意，唯一没有被自动注释的要素是全局变量——要为全局变量作注释，必须使用这个“快速上手”手册的下一节中描述的“phpDocumentor文档块”。另外还请注意，虽然include_once在include_path中指定了一个文件，phpDocumentor不会自动解析sample2.php，你必须手动指定需要解析的文件或目录。

    如果你觉得自己有冒险精神，可以用解析选项变量多次解析样本文件做做实验，，看看它们如何影响输出的文档。在命令行界面下查看选项，请键入
    $ phpdoc -h

以注释的方式为PHP源代码写文档

    现在打开sample2.php。它的内容和sample1.php相同，但包含了一个phpDocumentor文档块注释的完整阵列。请注意每一个文档块注释都是一个带有两个前导星号的C风格注释，例如：

   /**        *        */

复制代码

其它的注释都会被文档解析器忽略掉。请注意虽然文档的大部分是普通的英语，但在源代码中有些地方有少量的“@”字符。这个符号用来向解析器传递被称为标志的特殊命令。你可以阅读“phpDocumentor标志”和“phpDocumentor行内标志”来获得关于标志的更多信息

   /**        * {@inlinetag}        * this is @not a st andardtag - must begin a line.        * this is a valid {@inlinetag} also        * @standardtag        */

复制代码

为全局变量写文档

    注意sample2.php中下面这段代码：
[code]
   /**
       * Special global variable declaration DocBlock
       * @global integer $GLOBALS['_myvar']
       * @name $_myvar
       */
   $GLOBALS['_myvar'] = 6;

    在这个程序段中，我们看到了两个重要的标志，用于注释全局变量。@global标志用来告诉解析器如何找到全局变量声明。如果没有这个标志，解析器就不会为$_myvar生成任何注释。@global标志可能有很多种形式——千万别忘了指定类型和全局变量名称，而不需要描述，否则解析器会生成一个警告并且不能成功地注释该变量。

    现在，解析sample3.php并观察生成的文档。@name标志用于告诉解析器全局变量将如何被函数中的全局变量语句引用。

   /**
       * @global integer this is a function-based @global tag,
       *           because the variable name is missing
       */
   function someFunction()
   {
          global $_myvar;
   }

    这里的@global标志将把这些信息和函数体中的全局变量声明语句按照它们声明的顺序关联起来。

页面级的文档块(DocBlock)警告

    phpDocumentor最常问到的一个问题和页面级文档块的警告有密切联系。这一节将回答关于这一警告的任何问题，而这一答案能够回答所有这类问题。

    phpDocumentor把程序的要素和类组织为特别的组，称为包。在phpDocumentor的早期版本中，如果没有使用@package标志明确地指定包，程序会做出基于学习的猜测，猜测这个源要素属于哪个包。

    随着时间的过去，在很多情况下，phpDocumentor使用的猜测工具犯了明显的错误，一些源要素被归入了不正确的包。最后，开发者决定强制要求明确的@package标志，并且在顶层源要素缺少这个标志时发出警告。

    最大的混乱来自对文件的注释。phpDocumentor通过读取紧接在要素之前的文档块来为所有源要素作注释，比如：

   <?php
   /**
       * Documents the class following
       * @package SomePackage
       */
   class SomeClass {
   }
   ?>

    phpDocumentor也可以为文件的内容作注释。但是文档块怎么才能紧接在包含它的文件之前呢？一个简单的回答是假设一个文件中的第一个文档块为包含它的文件作注释，这个办法工作得很好，但也可能使人上当：

   <?php
   /**
       * Documents the class following or the file?
       * @package SomePackage
       */
   class SomeClass {
   }
   ?>

    同样的例子说明了歧义——这个文档块是为类作注释还是为文件作注释呢？为了解决这个歧义，phpDocumentor使用一个简单的算法来作决策。

1. 如果一个文件中的第一个文档块包含了@package标志，它是为文件作注释，除非它紧接在一个类定义前面。
2. 如果一个文件中的第一个文档块紧接在另一个文档块前面，它是为文件作注释。

   <?php
   /**
       * This is a file-level DocBlock
       *
       * A warning will be raised, saying that to document the define, use
       * another DocBlock
       * @package SomePackage
       */
   define('foo', 'bar');
   ?>

   <?php
   /**
       * This is a not a file-level DocBlock
       *
       * A warning will be raised, saying that no file-level DocBlock is present
       * and this DocBlock will attach to the define statement
       */
   define('foo', 'bar');
   ?>

   <?php
   /**
       * This is a not a file-level DocBlock
       *
       * A warning will be raised, saying that no file-level DocBlock is present
       * and this DocBlock will attach to the class statement
       */
   class foo {}
   ?>

   <?php
   /**
       * This is a not a file-level DocBlock, because it precedes a class declaration
       *
       * A warning will be raised, saying that no file-level DocBlock is present
       * and this DocBlock will attach to the class statement
       * @package SomePackage
       */
   class foo {}
   ?>

   <?php
   /**
       * This is a file-level DocBlock
       *
       * A warning will be raised saying that the package was assumed to be
       * SomePackage
       */
   /**
       * This is a normal class-level DocBlock
       *
       * this DocBlock will attach to the class statement
       * @package SomePackage
       */
   class foo {}
   ?>

   <?php
   /**
       * This is a file-level DocBlock
       *
       * A warning will be raised saying that the package was assumed to be
       * SomePackage because no @package tag was used
       */
   /**
       * This is a not a file-level DocBlock, because it precedes a class declaration
       *
       * A warning will be raised, saying that no file-level DocBlock is present
       * and this DocBlock will attach to the class statement
       * @package SomePackage
       */
   class foo {}
   ?>

   <?php
   /**
       * This is a file-level DocBlock
       *
       * No warning will be raised. This is the recommended usage
       * @package SomePackage
       */
   /**
       * This is a not a file-level DocBlock, because it precedes a class declaration
       *
       * This is also the recommended usage
       * @package SomePackage
       */
   class foo {}
   ?>

写外部文档并链接到源代码文档

    尽管直接从源代码解析文档非常有用，但仅有它自己是不够的。另外，真正有用的代码中的文档必须足够简洁，这样代码在文档的辅助下不至于显得太晦涩。外部文档对于完整的文档解决方案来说是必须的。然而，只有当外部文档能够链接到API源文档时才有用。对于一个经常改变的API文档，外部文档很容易就会过时。另外，外部文档必须是能够转换为其它格式的格式，这些其它格式包括HTML、PDF和XML。

    对于这些问题，phpDocumentor提供了一个简单而优雅的解决办法。文档块格式的外部文档能够很容易地转换为其它格式。使用行内标志，phpDocumentor能够生成很多不同格式但内容一致的手册，这是通过混合源代码和外部文档解析的结果实现的。你现在看到的文字就是一个基于文档块的文件，位于tutorials/phpDocumentor/phpDocumentor.quickstart.pkg。

   <refentry id="{@id}">
       <refnamediv>
      <refname>Simple Tutorial</refname>
      <refpurpose>The simplest Tutorial Possible</refpurpose>
       </refnamediv>
       <refsynopsisdiv>
      <author>
      Gregory Beaver
      <authorblurb>
          {@link mailto:[email protected] [email protected]}
      </authorblurb>
      </author>
       </refsynopsisdiv>
       <refsect1 id="{@id intro}">
      <para>Hello World</para>
       </refsect1>
   </refentry>


phpDocumentor工具的基本用法

    现在phpDocumentor已经安装好了，你怎么用它为一个项目作注释呢？首先，你必须清楚phpDocumentor是怎么把你的代码划分为包和子包的。如果你还不清楚这一点，现在就是阅读这个“快速上手”指南的“如何为代码写文档才能被phpDocumentor使用”(< http://manual.phpdoc.org/HTMLSma ... art.pkg.html#coding>)一节的最佳时机。

命令行工具：phpdoc

phpDocumentor的Web界面：docbuilder