如何文档化你的PHP类(一)

---

作者：stefano Locati 翻译：limodou  

　　你已经阅读过关于：面向对象编程可以帮助你管理你的大型web项目，并且你已经开始使用PHP来进行面向对象编程了吗？如果你已经编写了几个类应用在网站上并且你是一个有条理的人的话，那么你应该已经编写了关于它们的一些文档。但是如果你是一个象我一样的不拘小节的人，你只是会在类的源代码中加一些注释而没有别的文档。没有文档就很难记住方法的名字和它们的使用方法（参数和含义）。解决这种情况最典型的办法就是打开源代码文件，从成百上千的语句中查找。  

类似Javadoc的文档  
　　应该有一种好的方法----如果你曾经使用过Java语言，你将知道Javadoc文档系统。这个工具允许你在源代码文件注释中插入一些标记，这些标记可以被Javadoc工具进行分析以便生成一系列的HTML页面把你的类文档化。那样在编程的同时你可以开着浏览器并且可以得到类列表和带有说明的类方法的列表。在你开发web应用时，这个可以成为你的参考，提高工作效率和加快开发速度。  

　　我的意见是维护一个作为源代码内的引用文档要比维护一个独立的文档要容易和更实用，因为这个方法更容易保持更新。否则就非常容易变得懒惰从而将对文档的更新推后到无限期（如果一定要给它加个期限，我想是一万年）。相反使用象这样的一个工具，只有一点工作量就是在你正在修改的源代码附近更新一个标记，接着运行工具再一次生成更新过的HTML页面。  

一些php文档工具的预览  
　　在对上面了解了之后，我搜索了一下哪些是可用的，并且我发现了如下一些有趣的工具：  

　　phpSearchdoc是enzyme项目的一部分。因为enzyme 是一个巨大的项目，所以需要将其文档化。那里的开发人员已经编写了他们自已的文档系统并且他们非常慷慨地将其作为一个独立的包进行发布。得到的文档首先被写入数据库，然后可以被一些PHP脚本查看，象一个动态的web站点。  

　　从现存的信息中将用于分析的逻辑分离出来的想法相当好，然而phpSearchdoc(版本 1.01)不具有一个真正的分析器，而是从源文件，甚至包括注释中搜索关键字。事实上，对我来说碰巧发生过在我的注释中存在'function'单词，结果分析器愚蠢地认为在这个单词后面的词就是函数的名字。更不幸的是，我不巧在同一行放了一个单引号(')，接着我试图将数据写到数据库中，mysql作出了抱怨（出错了，因为单引号在 mysql中被用于分割字符串）。  

　　而且它的安装及运行相当困难，因为它还是一个alpha测试版。毕竟比起文档系统来说它更象是一个交叉引用生成器，正如我知道的，你不能在函数和方法中加入自已的注释。  

　　phpxref，就象名字所指的比起一个真正 的文档系统来似乎更象是面向交叉引用的生成处理。更进一步说它更适合于正常的过程化编程而不是面向对象编程。  

　　phpautodoc的目标是实现象Javadoc 应用于Java那样用于PHP。它看上去是满足我的文档需求的完美解决。为了试验它我不得不编译了PHP的CGI版本（我通常使用模块版本），因为生成器是用PHP编的。我可能容易地在一个Linux系统下编译和安装静态的执行程序，可以使用这些命令：  

rm config.chche  
make clean  
./configure  
make  
cp php /usr/local/bin  

　　我决定对它自已的PHP源码进行测试，并且我发现它只有部分可以工作：它只能够生成类的文档（生成整齐的格式），但是不能生成小结。我不知道是否这个只是碰巧发生在我的机器上，但是在试图生成小结时却因为core dump(内核崩溃)而停止（PHP 4.0 pl2，RedHat 6.2环境）。假如在你的机器/usr/local/bin下安装了PHP执行版本，调用它的语法是（为了得到结果我不得不给出php文件和输出目录的全路径）  

./phpautodoc -o  

　　phpdoc是一个用来维护在Web站点上的php 文件，并且它非常适合分布式开发方式。文档是从数据库中生成；在安装之后，你可以使用web界面来增加你的类将其文档化。这个的确有意思，但是它是一种低级的从源代码中分离文档的维护方法，这一点就我来说不是非常方便。  

通用工具  
　　在经受了试验所有这些工具但却得不到怎么成功的挫折之后，直到Pear Project提出了一种标准的解决方法，我发现了一个与PHP完全无关的可工作的工具在Open Source Projects at Apple站点。项目的名字是 HeaderDoc。就象站点所说的" HeaderDoc是一种从C或C++头文件的注释中生成HTML的引用文档的工具。它是用Perl编写的以便于移植。与JavaDoc 相似，它允许开发者容易地文档化他们的接口，并且将接口信息输出到HTML。"  

　　是的，你看的没错，HeaderDoc只支持C和C++。没有其它的语言，但是它不象JavaDoc，它大部分依赖写在注释中的标记，所以只要做些小改动（我会在后面解释）就可以很好的用在PHP上。这些标记同JavaDoc很象，HeaderDoc标记的一些例子是@class，@function和@var。  

文档化一个类  
　　OK，让我们现在进入细节吧。首先让我们看一下一个类如何被文档化。  

--------------------------------------------------------------------------------  
/*! @class BagItem  
    @abstract An item in the shopping bag - it is a shopitem with quantity  
    @discussion A BagItem object may be constructed without previous  
    instantiation of neither ShopItem nor Product  
*/  
--------------------------------------------------------------------------------  

文档化一个类。可以在左边的帧选择类的方法。  

　　第一件需要注意的事情是用在打开注释上的风格不完全象JavaDoc注释/**(一个斜线和两个星号)，而是换成/*!(一个斜线，一个星号和一个感叹号) 。标记使用也不一样，但是它们以相似的方式工作。例如，第一个标记是@class标记，它用于文档化一个类，这个标记跟着类的名字。下一个标记是@abstract 标记，它  
是一个可选的标记，用少量词语来描述一个类的含义，同时@discussion 标记是另一个可选的标记，用于进一步的讨论。当然由你来决定是在@discussion标记中描述所有的事情还是使用@abstract来处理，但是要记住，一般来说，你使用的标记越精确，结果就越好。  

原作者：limodou  
来源：PHPX