寫文檔是一項乏味卻不得不做的工作，而編寫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
