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