如何文檔化你的PHP類(一)

---

作者：stefano Locati 翻譯：limodou

　　你已經(jīng)閱讀過關(guān)于：面向?qū)ο缶幊炭梢詭椭�你管理你的大型web項目，并且你已經(jīng)開始使用PHP來進行面向?qū)ο缶幊塘藛�？如果你已�?jīng)編寫了幾個類應(yīng)用在網(wǎng)站上并且你是一個有條理的人的話，那么你應(yīng)該已經(jīng)編寫了關(guān)于它們的一些文檔。但是如果你是一個象我一樣的不拘小節(jié)的人，你只是會在類的源代碼中加一些注釋而沒有別的文檔。沒有文檔就很難記住方法的名字和它們的使用方法（參數(shù)和含義）。解決這種情況最典型的辦法就是打開源代碼文件，從成百上千的語句中查找。

類似Javadoc的文檔
　　應(yīng)該有一種好的方法----如果你曾經(jīng)使用過Java語言，你將知道Javadoc文檔系統(tǒng)。這個工具允許你在源代碼文件注釋中插入一些標(biāo)記，這些標(biāo)記可以被Javadoc工具進行分析以便生成一系列的HTML頁面把你的類文檔化。那樣在編程的同時你可以開著瀏覽器并且可以得到類列表和帶有說明的類方法的列表。在你開發(fā)web應(yīng)用時，這個可以成為你的參考，提高工作效率和加快開發(fā)速度。

　　我的意見是維護一個作為源代碼內(nèi)的引用文檔要比維護一個獨立的文檔要容易和更實用，因為這個方法更容易保持更新。否則就非常容易變得懶惰從而將對文檔的更新推后到無限期（如果一定要給它加個期限，我想是一萬年）。相反使用象這樣的一個工具，只有一點工作量就是在你正在修改的源代碼附近更新一個標(biāo)記，接著運行工具再一次生成更新過的HTML頁面。

一些php文檔工具的預(yù)覽
　　在對上面了解了之后，我搜索了一下哪些是可用的，并且我發(fā)現(xiàn)了如下一些有趣的工具：

　　phpSearchdoc是enzyme項目的一部分。因為enzyme 是一個巨大的項目，所以需要將其文檔化。那里的開發(fā)人員已經(jīng)編寫了他們自已的文檔系統(tǒng)并且他們非�？犊�地將其作為一個獨立的包進行發(fā)布。得到的文檔首先被寫入數(shù)據(jù)庫，然后可以被一些PHP腳本查看，象一個動態(tài)的web站點。

　　從現(xiàn)存的信息中將用于分析的邏輯分離出來的想法相當(dāng)好，然而phpSearchdoc(版本 1.01)不具有一個真正的分析器，而是從源文件，甚至包括注釋中搜索關(guān)鍵字。事實上，對我來說碰巧發(fā)生過在我的注釋中存在'function'單詞，結(jié)果分析器愚蠢地認(rèn)為在這個單詞后面的詞就是函數(shù)的名字。更不幸的是，我不巧在同一行放了一個單引號(')，接著我試圖將數(shù)據(jù)寫到數(shù)據(jù)庫中，mysql作出了抱怨（出錯了，因為單引號在 mysql中被用于分割字符串）。

　　而且它的安裝及運行相當(dāng)困難，因為它還是一個alpha測試版。畢竟比起文檔系統(tǒng)來說它更象是一個交叉引用生成器，正如我知道的，你不能在函數(shù)和方法中加入自已的注釋。

　　phpxref，就象名字所指的比起一個真正 的文檔系統(tǒng)來似乎更象是面向交叉引用的生成處理。更進一步說它更適合于正常的過程化編程而不是面向?qū)ο缶幊獭?br>
　　phpautodoc的目標(biāo)是實現(xiàn)象Javadoc 應(yīng)用于Java那樣用于PHP。它看上去是滿足我的文檔需求的完美解決。為了試驗它我不得不編譯了PHP的CGI版本（我通常使用模塊版本），因為生成器是用PHP編的。我可能容易地在一個Linux系統(tǒng)下編譯和安裝靜態(tài)的執(zhí)行程序，可以使用這些命令：

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

　　我決定對它自已的PHP源碼進行測試，并且我發(fā)現(xiàn)它只有部分可以工作：它只能夠生成類的文檔（生成整齊的格式），但是不能生成小結(jié)。我不知道是否這個只是碰巧發(fā)生在我的機器上，但是在試圖生成小結(jié)時卻因為core dump(內(nèi)核崩潰)而停止（PHP 4.0 pl2，RedHat 6.2環(huán)境）。假如在你的機器/usr/local/bin下安裝了PHP執(zhí)行版本，調(diào)用它的語法是（為了得到結(jié)果我不得不給出php文件和輸出目錄的全路徑）

./phpautodoc -o

　　phpdoc是一個用來維護在Web站點上的php 文件，并且它非常適合分布式開發(fā)方式。文檔是從數(shù)據(jù)庫中生成；在安裝之后，你可以使用web界面來增加你的類將其文檔化。這個的確有意思，但是它是一種低級的從源代碼中分離文檔的維護方法，這一點就我來說不是非常方便。

通用工具
　　在經(jīng)受了試驗所有這些工具但卻得不到怎么成功的挫折之后，直到Pear Project提出了一種標(biāo)準(zhǔn)的解決方法，我發(fā)現(xiàn)了一個與PHP完全無關(guān)的可工作的工具在Open Source Projects at Apple站點。項目的名字是 HeaderDoc。就象站點所說的" HeaderDoc是一種從C或C++頭文件的注釋中生成HTML的引用文檔的工具。它是用Perl編寫的以便于移植。與JavaDoc 相似，它允許開發(fā)者容易地文檔化他們的接口，并且將接口信息輸出到HTML。"

　　是的，你看的沒錯，HeaderDoc只支持C和C++。沒有其它的語言，但是它不象JavaDoc，它大部分依賴寫在注釋中的標(biāo)記，所以只要做些小改動（我會在后面解釋）就可以很好的用在PHP上。這些標(biāo)記同JavaDoc很象，HeaderDoc標(biāo)記的一些例子是@class，@function和@var。

文檔化一個類
　　OK，讓我們現(xiàn)在進入細(xì)節(jié)吧。首先讓我們看一下一個類如何被文檔化。

--------------------------------------------------------------------------------
/*! @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
*/
--------------------------------------------------------------------------------

文檔化一個類�？梢栽谧筮叺膸�選擇類的方法。

　　第一件需要注意的事情是用在打開注釋上的風(fēng)格不完全象JavaDoc注釋/**(一個斜線和兩個星號)，而是換成/*!(一個斜線，一個星號和一個感嘆號) 。標(biāo)記使用也不一樣，但是它們以相似的方式工作。例如，第一個標(biāo)記是@class標(biāo)記，它用于文檔化一個類，這個標(biāo)記跟著類的名字。下一個標(biāo)記是@abstract 標(biāo)記，它
是一個可選的標(biāo)記，用少量詞語來描述一個類的含義，同時@discussion 標(biāo)記是另一個可選的標(biāo)記，用于進一步的討論。當(dāng)然由你來決定是在@discussion標(biāo)記中描述所有的事情還是使用@abstract來處理，但是要記住，一般來說，你使用的標(biāo)記越精確，結(jié)果就越好。

原作者：limodou
來源：PHPX