PHPDoc/PHPDocumentor生成API文檔

PHPDocumentor是一個用PHP寫的強大的文檔自動生成工具，對於有規范注釋的php程序，能夠快速生成具有結構清晰、相互參照、索引等功能的API文檔。舊版本是PHPDoc，PHPDoc是PEAR下面的一個非常優秀的模塊，類似於Javadoc。從1.3.0開始，更名為phpDocumentor，新版本新加了對php5語法的支持，同時，可以通過在客戶端瀏覽器上操作生成文檔，文檔可以轉換為PDF、HTML、CHM等格式的文檔，這樣非常有利於代碼的升級、維護、移交等。

前提：安裝的前提是已經安裝了php環境，我安裝的是xampp集成開發環境。

1.PHPDoc的結構及功能 
PHPDoc是全部采用OOP的思想來編寫的，這也是PEAR所推薦的方式，PHPDoc的工作原理：PHPDoc掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取需要分析的注釋，然后分析注釋中的專用的tag，生成xml文件，接着根據已經分析完的類和模塊的信息，建立相應的索引，生成xml文件對於生成的xml文件，使用定制的模板輸出為html文件。從設計上來說，PHPDoc使用了2個超類：PhpdocObject和PhpdocError。這是整個PHPDoc的基本類，這種方式也是PEAR所推薦的。當你編寫應用框架時，最好能夠有一個基本的超類，而其他的子類或者是功能類都有一個共同的祖先。在掃描源代碼過程中，PHPDoc使用的是類似GREP的形式。PHPDoc令人滿意的另一方面是其分析結果是以XML形式保存的，這就意味着其他應用程序可以共享這個數據，同時PHPDoc也提供了相應的接口，你可以實現這個接口，把API文檔生成其他的形式，比如PDF，LATEX，WORD等。目前，PHPDoc的分析結果可以以HTML形式表現，由於使用了模板機制，可以很方便地定制風格。

2.安裝PHPDoc 
安裝方式有兩種，一是下載源碼安裝，另一種是通過pear安裝。

第一種方法： 
第一步：安裝pear 
使用dos窗口進入php安裝目錄，有個文件叫go-pear.bat，如果沒有，建議到網上下載go-pear.phar，然后在dos窗口下運行 go-pear.phar, 從而安裝pear。

php go-pear.phar 

第二步：安裝phpdoc

Pear install phpDocumentor 

在phpDocumentor成功安裝后，php安裝目錄下會多出來一個phpdoc.bat。這個文件就是我們用來生成文檔的批處理文件。 
在phpdoc.bat所在目錄下，輸入

Phpdoc –h 

會得到一個phpDocumentor的詳細參數列表。先看看最重要的幾個吧。

-d 這個目錄代表着需要生成文檔的原始php文件目錄（注意是目錄） -t 這個目錄代表着生成的文檔存放目錄 -o 這個參數代表着生成的文檔格式，例如html格式，參數就是 HTML:frames:phpedit

第三步：生成文檔 
生成文檔的命令就是：

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1" -o "HTML:frames:phpedit"

可以看到，解析完成后，在目標目錄下生成很多html文件，打開index.html文件，就是我們需要的文檔，如下圖所示。

第二種方法： 
第一步：下載PHPDoc壓縮文件（phpdoc.zip），地址如下： 
http://star7th-wordpress.stor.sinaapp.com/uploads/2013/04/phpdoc.zip

第二步：解壓到某一個目錄 
打開phpdoc.bat，編輯第16行：

SET phpCli=D:\xampp\php\php.exe

配置phpCli 為自己php.exe文件的路徑即可。

第二步：dos窗口，進入文件的解壓目錄，然后執行解析文檔命令即可。

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1" -o "HTML:frames:phpedit"

以上是安裝phpDocumentor1版本，目前已經更新到phpDocumentor2版本了，version2的安裝也很簡單。

第一步：安裝pear（同上） 
此處給出下載地址：http://pear.php.net/go-pear.phar 
將 go-pear.phar 放到 PHP 目錄下執行安裝命令：

php go-pear.phar

下面會執行輸入 system

然后一路回車安裝完畢。

第二步：接下來安裝類關系繪圖用到的工具

pear install image_graphviz 
下載 http://www.graphviz.org/Download_Windows.php graphviz-2.38.msi 
安裝后，注意環境變量 path 添加上該 bin 的路徑，重啟電腦，否則無法生效

第三步：安裝 phpDocumentor

pear channel-discover pear.phpdoc.org pear install phpdoc/phpDocumentor

稍等一會，安裝步驟完成！ 
注意：兩個軟件安裝后的目錄都在PHP 下的 pear 下面：

php/pear/PhpDocumentor
php/pear/Image

顯然：version2 比version1速度快了很多。