当前位置:首页> PHP教程> PHP精通
关键字
文章内容
如何文档化你的PHP类(一)
 
 
修改时间:[2009/07/12 06:59]    阅读次数:[664]    发表者:[起缘]
 
如何文档化你的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 pl2RedHat 6.2环境。假如在你的机器/usr/local/bin下安装了PHP执行版本调用它的语法是为了得到结果我不得不给出php文件和输出目录的全路径 



./phpautodoc -



  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  
 
 
 
 
 
 

威尼斯人唯一官网