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

2014-06-05 为码而活 PHP教程 关注809次 已收录
当前位置：波比源码 > 如何文档化你的PHP类(一)
正文概述

如何文档化你的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

波比源码 – 精品源码模版分享 | www.bobi11.com
1. 本站所有资源来源于用户上传和网络，如有侵权请邮件联系站长！
2. 分享目的仅供大家学习和交流，您必须在下载后24小时内删除！
3. 不得使用于非法商业用途，不得违反国家法律。否则后果自负！
4. 本站提供的源码、模板、插件等等其他资源，都不包含技术服务请大家谅解！
5. 如有链接无法下载、失效或广告，请联系管理员处理！
6. 本站资源售价只是赞助，收取费用仅维持本站的日常运营所需！
7. 本站源码并不保证全部能正常使用，仅供有技术基础的人学习研究，请谨慎下载
8. 如遇到加密压缩包，请使用WINRAR解压,如遇到无法解压的请联系管理员！

波比源码 » 如何文档化你的PHP类(一)
分享到：

相关推荐

130 评论

  4. order ampicillin 500mg trimethoprim cost buy generic erythromycin 250mg

  5. order lamotrigine 50mg online cheap prazosin usa tretinoin buy online

  11. cialis 5mg für männer viagra 50mg kaufen sildenafil 50mg bestellen

  20. linezolid price play roulette real casino slots online

  24. brand triamcinolone 10mg clarinex usa desloratadine online buy

  30. purchase ranitidine generic zantac order buy celebrex 200mg pill

  32. buy simvastatin 10mg generic simvastatin order buy generic proscar 1mg

  41. buy albuterol 100mcg sale cipro 500mg us order ciprofloxacin 1000mg online

  48. order alendronate 35mg generic motrin oral buy ibuprofen 600mg pill

  55. buy generic doxycycline 200mg brand vibra-tabs order acyclovir 400mg without prescription

  56. generic zetia 10mg sumycin sale methotrexate 2.5mg for sale

  66. oral methotrexate reglan tablet order generic metoclopramide

  76. order diflucan 100mg online cipro 1000mg oral buy cipro 500mg without prescription

  79. order avanafil 100mg pill avana pill voltaren 100mg drug

  87. lasix order online buy lasix sale order ventolin inhalator online

  93. diamox canada brand imdur imuran 25mg brand

  94. order lanoxin 250 mg without prescription generic telmisartan molnunat 200 mg ca

  97. how to get dapoxetine without a prescription dapoxetine brand orlistat 120mg usa

  109. buy azathioprine 25mg purchase imuran micardis online order

  110. lansoprazole buy online generic prevacid buy protonix 40mg generic

  112. avlosulfon brand buy adalat order perindopril 8mg without prescription

  115. cordarone 200mg cheap cordarone pills dilantin 100 mg canada

  116. purchase albendazole pills oral provera how to buy provera

  119. purchase macrodantin pill buy pamelor 25 mg order pamelor 25mg generic

  125. buy capoten 25mg pill brand tegretol carbamazepine tablet

  126. buy generic bupropion 150 mg zyban 150 mg usa strattera 10mg oral

  129. buy prozac 40mg for sale prozac 20mg ca buy femara without prescription

评论已关闭

Hi, 如果你对这款模板有疑问，可以跟我联系哦！

联系站长
赞助VIP 享更多特权，建议使用 QQ 登录
QQ登录
喜欢我嘛？喜欢就按“ctrl+D”收藏我吧！♡