使用phpdoc/phpDocumentor來產生api文檔

phpDocumentor是一個非常強大的文檔自動產生工具，利用它可以協助我們編寫規範的注釋，產生易於理解，結構清晰的文檔，

對我們的代碼升級，維護,移交等都有非常大的協助。

網上關於phpdoc的文檔的介紹雖然不少，但是有點麻煩：

1、網上通常介紹的內容太多，不容易被新手看懂。個人覺得，教程應該本著簡單易懂，在能解決問題的前提下，能有多簡單就多簡單。

更多的內容，應該以附錄的形式，或者留下其他更詳細的資料連結供讀者去閱讀（而不是把一大塊都複製進自己的文章）

2、phpdoc的安裝稍微麻煩。他們沒有介紹一種簡單易上手的方法給讀者

3、phpdoc的預設編碼是ISO-8859-1，此時產生的HTML文檔會中文亂碼。儘管說網上有提供瞭解決方案??但是，為什麼不直接提供一個可支援中文的版本給讀者呢？

基於以上幾點，我想寫篇博文，跟大家分享一個使用phpdoc的簡單方法(windows環境下)

在使用phpdoc之前，你首先需要瞭解代碼注釋的文法規則（如果你已經懂，請忽略）。

可參考維基本科 http://zh.wikipedia.org/wiki/PHPDoc 中關於注釋格式的描述部分。

接著，可下載這個經過最佳化的phpdoc版本:

http://star7th-wordpress.stor.sinaapp.com/uploads/2013/04/phpdoc.zip

下載後解壓，比如說解壓到”D:/phpdoc”路徑下。

用文字編輯器開啟phpdoc.bat（注意，不是雙擊運行），第16行：

SET phpCli=D:\Program Files\php5.3.11\php.exe

將這裡的PHP.exe的路徑改為你電腦的php環境執行檔案所在的路徑。（如果你是PHPer，我相信你在本機有安裝了php環境吧。）

然後，開啟命令提示字元。（開始-運行-cmd），在命令列中，進入phpdoc所在的目錄，（比如說，輸入“cd D:/phpdoc”）。

進入目錄後，輸入下面的命令，便可快速產生HTML文檔：

phpdoc -d D:\website\Api -t D:\website\Api\doc -dn shilianwang -dc shilianwang -ti 事連網文檔 -o HTML:Smarty:PHP

上述命令中，D:\website\Api是源php檔案所在目錄。D:\website\Api\doc 是產生的文檔存放目錄。

shilianwang是子目錄，包、標題。HTML:Smarty:PHP 表示使用HTML模組產生

上面的命令，如果你想詳細瞭解，可在命令列輸入phpdoc -h ，瞭解更多。

最後，附上三種：

注釋的樣式：

該注釋產生的：

PhpDocumentor手冊-安裝和標籤使用

謝謝關注websites部落格!

