如何文檔化你的PHP類

你已經閱讀過關於：物件導向編程可以協助你管理你的大型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來處理，但是要記住，一般來說，你使用的標記越精確，結果就越好。

文檔化函數或方法
　　成員函數或方法使用@function標記被文檔化。

--------------------------------------------------------------------------------
/*! @function getItemingroup
@abstract gets a bagitem of a given group and a given position
@param groupno int - the delivery group ordinal position in the bag
@param pos int - the position of the bagitem within the group
@result Object - the BagItem in a given position of given group
or -1 if it could not be found
*/
--------------------------------------------------------------------------------

文檔化一個方法。

　　@function標記聲明了一個函數並且後面跟著函數或成員函數名。然後你可以象前面一樣使用 @abstract和@discussion標記。然而還有兩個額外的標記。@param標記用於描述函數的參數；第一個詞假設為變數的名字，其它的則為任意的文本描述。我建議要聲明想要的變數類型，儘管PHP不是一個強型別語言。 @result標記被用於描述傳回值。

文檔化變數
　　變數或類變數都使用@var標記來描述。在這個標記中，第一個詞被認為是變數的名字，同時其它的則為任意的文本描述。象前面一樣，我建議寫出所期望的變數類型是好的做法。它也是一個文檔化所有類變數的好主意。


文檔化一個類變數。

--------------------------------------------------------------------------------
/*! @var idsession string - an unique session identifier */
var $idsession;
--------------------------------------------------------------------------------
最後接觸
--------------------------------------------------------------------------------
/*! @header myprojectname
@abstract a virtual store to shop on mars
@discussion The difference [...]
*/
--------------------------------------------------------------------------------
　　@header標記用來提供一些關於被文檔化的項目或類組的一般性資訊。@header標記本身跟著項目的名字 ，而且可以用@abstract標記和@discussion標記來補充說明。因為類通常存在於不同的檔案中（一個檔案一個類，且用類的名字給檔案名稱字是一種好的想法），你可能想知道應該將@header 標記放在什麼地方。答案很讓人吃驚，哪都可以。我的建議是：如果它比較長就把它放在一個獨立的檔案中，或如果是一個簡短的說明就把它放在最重要的類的前面。

如何修改指令碼用於PHP
　　從Apple得到的初始的HeaderDoc指令碼是用於C或C++標頭檔的，所以要用在PHP中需要對它做一些小改動 。如果你對細節沒有興趣，你可以從這裡下 載，並且跳過下面部分。
　　修改來源程式所做的唯一的事情就是在主perl檔案中，使指令碼可以接受.php和.php3尾碼。

--------------------------------------------------------------------------------
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html
195c195
< ($rootFileName = $filename) =~ s/.(h|i)$//;
---
> ($rootFileName = $filename) =~ s/.(h|i|php|php3)$//;
--------------------------------------------------------------------------------
運行指令碼
　　在安裝完指令碼之後，假設你的類放在classes子目錄下，並且你想將產生的文檔放在docs目錄下，你應該執行這個命令：

headerdoc2html -o docs classes/*.php

　　不幸的是如果存在多個PHP檔案，這個指令碼有一個壞習慣就是將那些檔案分割到不同的目錄中去，使得在類的文檔中瀏覽變得很困難。而且因為初始的指令碼是為C/C++標頭檔所寫的（標頭檔中只有類和函數的聲明而沒有他們的定義），指令碼會將函數名下的所有代碼輸出，直到碰到";"，所以典型的就是代碼的第一行。

　　但是在你好不容易讀到現在卻感到絕望之前，放鬆，因為我寫了一段簡單的指令碼來解決這兩個問題。

--------------------------------------------------------------------------------
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "
" > docs/all.php
headerdoc2html -o docs docs/all.php
rm docs/all.php
--------------------------------------------------------------------------------
　　如果你想知道為什麼我在這裡使用tr命令而不是都用sed來做，原因就是用在仍然用在RedHat 6.2上的sed 3.02版本不處理分行符號。應該替換成新的版本sed 3.02a。如果你對sed感興趣，可以看SED FAQ。

　　祝你的文檔化工作好運！