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

学习Go语言文档中的os.Stdout.Write函数实现标准输出在Go语言中,标准输出是通过os.Stdout来实现的。os.Stdout是一个*os.File类型的变量,它代表了标准输出设备。为了将内容输出到标准输出,可以使用os.Stdout.Write函数。本文将介绍如何使用os.Stdout.Write函数实现标准输出,并提供具体的代码示例。os.

Java文档解读:StringBuilder类的substring()方法详细介绍引言:在Java编程中,字符串的处理是非常常见的操作之一。而Java提供了一系列关于字符串处理的类和方法,其中StringBuilder类是常用于频繁字符串操作的选择。在StringBuilder类中,substring()方法是一个非常有用的方法,用于截取字符串的子串。本文将

PHP如何对接淘宝商品搜索API文档淘宝是中国最大的电子商务平台之一,拥有庞大的商品库存和用户群体。对于开发者来说,通过对接淘宝的API接口,可以获取商品信息、推广活动以及进行交易等功能,从而实现个性化的商业应用。本文将介绍如何使用PHP语言对接淘宝商品搜索API,帮助开发者快速构建自己的电商应用。第一步:注册成为淘宝开发者在开始之前,需要先注册成为淘宝开发

Java文档解读:HashSet类的contains()方法用法详解HashSet类是Java中常用的集合类之一,它实现了Set接口,并且基于哈希表的数据结构,具有高效的插入、删除和查找操作。其中,contains()方法是HashSet类提供的一个重要方法,用于判断集合中是否包含指定的元素。本文将详细解析HashSet类的contains()方法的用法,并

学习Go语言文档中的os.Stderr.Write函数实现标准错误输出,需要具体代码示例在Go语言中,标准错误输出通常用于向用户报告程序中的错误信息。而os.Stderr.Write函数可以实现将错误信息输出到标准错误输出。下面我们将通过具体的代码示例来展示如何使用这个函数。首先,我们需要导入os包来访问标准错误输出。代码如下:packagemaini

ThinkPHP6是一款基于PHP语言开发的Web应用框架,该框架一经推出就受到了广泛的欢迎和使用,目前已经成为国内最流行的一款PHP框架之一。在这篇文章中,我们将深入探讨ThinkPHP6框架的核心,帮助读者更好地掌握该框架。一、框架的概述ThinkPHP6是一个企业级的开发框架,它采用MVC(Model-View-Controller)模式进行开发,拥有

掌握Go语言文档中的time.NewTimer函数实现单次定时器,并附上具体代码示例。时间作为我们生活的基准,定时器是编程中非常常用的工具之一。在Go语言中,我们可以使用time包来处理时间相关的操作,其中NewTimer函数可以用于创建一个单次定时器。本文将介绍如何使用NewTimer函数来实现一个简单的单次定时器,并附上具体代码示例。在Go语言中,tim

Java文档解读:System类的exit()方法用法解析,需要具体代码示例System类是Java中的一个重要类,它提供了许多与系统相关的功能和方法。其中,exit()方法是System类中的一个常用方法,用于终止当前正在运行的Java虚拟机。在本文中,我们将对exit()方法的用法进行解析,并给出具体的代码示例。exit()方法的定义如下:public


熱AI工具

Undresser.AI Undress
人工智慧驅動的應用程序,用於創建逼真的裸體照片

AI Clothes Remover
用於從照片中去除衣服的線上人工智慧工具。

Undress AI Tool
免費脫衣圖片

Clothoff.io
AI脫衣器

AI Hentai Generator
免費產生 AI 無盡。

熱門文章

熱工具

mPDF
mPDF是一個PHP庫,可以從UTF-8編碼的HTML產生PDF檔案。原作者Ian Back編寫mPDF以從他的網站上「即時」輸出PDF文件,並處理不同的語言。與原始腳本如HTML2FPDF相比,它的速度較慢,並且在使用Unicode字體時產生的檔案較大,但支援CSS樣式等,並進行了大量增強。支援幾乎所有語言,包括RTL(阿拉伯語和希伯來語)和CJK(中日韓)。支援嵌套的區塊級元素(如P、DIV),

SublimeText3 英文版
推薦:為Win版本,支援程式碼提示!

Dreamweaver Mac版
視覺化網頁開發工具

Atom編輯器mac版下載
最受歡迎的的開源編輯器

禪工作室 13.0.1
強大的PHP整合開發環境