PHP文檔工具_PHP

寫文檔是一項乏味卻不得不做的工作，而編寫API級的文檔更是意味著大量的重複勞動和難以保持的一致性。這裡我們要推薦給大家的，是支援PHP5文法分析的文檔工具——phpDocumentor。

使用phpDocumentor不僅可以自動從代碼中提取出函數和方法定義，還可以自動處理各個class之間的關係，並據此產生class tree。你還可以選擇將文檔產生html、chm或者pdf。有了phpDocumentor，文檔工作變得輕鬆了很多。



安裝phpDocumentor

在pear下安裝phpDocumentor是一件極其簡單的事情，只需要在cmd視窗中cd 到php安裝目錄下，然後輸入

Pear install phpDocumentor


Pear就會自己下載並完成phpDocumentor的安裝。

在phpDocumentor成功安裝後，php安裝目錄下會多出來一個phpdoc.bat。這個檔案就是我們用來產生文檔的批次檔了。



phpDocumentor是phpDoc的升級版本，是專門為支援php5文法而重寫的文檔工具，當你的php版本為5時，運行phpDoc.bat，它會自動去調用phpDocumentor。所以文章中的提到的phpDoc和phpDocumentor實際上是相同的。




在phpdoc.bat所在目錄下，輸入

Phpdoc –h


會得到一個phpDocumentor的詳細參數列表。

我們從其中選出幾個常用的來看看：



-f
要進行分析的檔案名稱，多個檔案用逗號分割

-d
要分析的目錄，多個目錄用逗號分割

-t
產生的文檔的存放路徑

-o
輸出的文檔格式，結構為輸出格式:轉換器名:模版目錄，例如：HTML:frames:phpedit




我們會用到的就這幾個了，其他的命令請大家閱讀help的提示資訊。



試用phpDocumentor

下面我們就以pear中的phpUnit2為例，示範一下如何使用phpDocumentor來產生文檔。

首先，把我們需要的參數確定下來：



-d
C:\Program Files\EasyPHP5\php\PEAR\PHPUnit2

-t
C:\Program Files\EasyPHP5\php\phpunit2doc

-o
HTML:frames:phpedit


根據上邊的參數，我們組合出下邊的命令：

Phpdoc -d “C:\Program Files\EasyPHP5\php\PEAR\PHPUnit2” -t “C:\Program Files\EasyPHP5\php\phpunit2doc” -o “HTML:frames:phpedit”


運行上邊的命令後，phpDocumentor開始解析源檔案並輸出工作資訊。




命令運行完成後，我們的文檔就已經產生好了。 進入我們指定的目標目錄，用瀏覽器開啟index.html就可以看見產生的文檔了。 文檔介面由frame分成了三個部分，左上是包資訊，左下是導航資訊，右邊則是詳細的資訊呈現頁。




上邊的圖很清楚地描述出了文檔的內容：

索引、函數列表、類列表、檔案清單和子包。

點擊上邊的class(es)連結，我們可以清晰的看見整個包的class tree。




我們點擊其中一個class，就進入了class的描述頁面。

Class描述頁面主要包含以下幾方面內容：



l 描述：著作權、作者、類層次等

l 類變數

l 類常量

l 方法

l 繼承的變數

l 繼承的方法：非常有用的一個功能






怎麼樣，是不是很詳細呢？如果要產生chm，可以把前邊的-o參數改為”CHM:default: default”，這樣phpDocumentor會為你產生好chm專案檔，只要用微軟的chm工具進行編譯就可以得到可用的chm檔案了。



用phpDocumentor為自己的代碼產生文檔

雖然phpDocumentor可以自動從代碼中分析出一些資訊，但是，要形成一份詳盡的文檔還是需要我們在編碼中進行配合的。為了讓phpDocumentor讀懂我們的代碼，我們需要注意一些編碼規範和在注釋中增加一些tag：





@author
作者資訊

@const
由define定義的常量

@deprecate
不建議使用的API

@global
全域變數

@package
包資訊

@param
函數參數

@return
傳回值

@see
參考函數

@since
引入時間

@static
靜態變數

@var
類成員變數




這裡只是簡單的列出了常用的一些Tag，大家可以閱讀phpDocumentor的文檔，裡邊有非常詳細的編碼規範。關於phpDocumento就介紹到這裡，希望大家都能好好利用這個工具來規範自己的文檔。



PS：phpDocumentor也有Web介面的，你可以訪問http://phpdoc.org擷取Web版本。Web版本的安裝很簡單，直接放到web可以訪問的目錄就可以運行了。





PHP：5.0.0

OS: 平台獨立，本文示範OS為windows

