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 FilesEasyPHP5phpPEARPHPUnit2
-t
C:Program FilesEasyPHP5phpphpunit2doc
-o
HTML:frames:phpedit
根據上邊的參數,我們組合出下邊的命令:
Phpdoc -d “C:Program FilesEasyPHP5phpPEARPHPUnit2” -t “C:Program FilesEasyPHP5phpphpunit2doc” -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

You May Also Like