1. 什么是phpDocumentor ?

PHPDocumentor是一個(gè)用PHP寫(xiě)的工具，對于有規范注釋的php程序，它能夠快速生成具有相互參照,索引等功能的API文檔。老的版本是 phpdoc，從1.3.0開(kāi)始，更名為phpDocumentor，新的版本加上了對php5語(yǔ)法的支持，同時(shí)，可以通過(guò)在客戶(hù)端瀏覽器上操作生成文檔，文檔可以轉換為PDF,HTML,CHM幾種形式，非常的方便。

PHPDocumentor工作時(shí)，會(huì )掃描指定目錄下面的php源代碼，掃描其中的關(guān)鍵字，截取需要分析的注釋?zhuān)缓蠓治鲎⑨屩械膶?zhuān)用的tag，生成 xml文件，接著(zhù)根據已經(jīng)分析完的類(lèi)和模塊的信息，建立相應的索引，生成xml文件，對于生成的xml文件，使用定制的模板輸出為指定格式的文件。

2. 安裝phpDocumentor

和其他pear下的模塊一樣，phpDocumentor的安裝也分為自動(dòng)安裝和手動(dòng)安裝兩種方式，兩種方式都非常方便：

a．通過(guò)pear 自動(dòng)安裝

在命令行下輸入

pear install PhpDocumentor

b．手動(dòng)安裝

在http://manual.phpdoc.org/下載最新版本的PhpDocumentor（現在是1.4.2），把內容解壓即可。

3．怎樣使用PhpDocumentor生成文檔

a. 命令行方式

在phpDocumentor所在目錄下，輸入

Php -h

會(huì )得到一個(gè)詳細的參數表，其中幾個(gè)重要的參數如下：

-f 要進(jìn)行分析的文件名，多個(gè)文件用逗號隔開(kāi)

-d 要分析的目錄，多個(gè)目錄用逗號分割

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

-o 輸出的文檔格式，結構為輸出格式：轉換器名：模板目錄。

-dn 默認包名稱(chēng) (defaultpackagename)

-cs 生成文檔編碼（charset）

例如：phpdoc -d "D:\www\billing" -t "d:\temp\billing" -o "html:frames:earthli" -dn "Billing" -cs "utf8"

b. Web界面生成

在新的phpdoc中，除了在命令行下生成文檔外，還可以在客戶(hù)端瀏覽器上操作生成文檔，具體方法是先把PhpDocumentor的內容放在apache目錄下使得通過(guò)瀏覽器可以訪(fǎng)問(wèn)到，訪(fǎng)問(wèn)后顯示如下的界面：

點(diǎn)擊files按鈕，選擇要處理的php文件或文件夾，還可以通過(guò)該指定該界面下的Files to ignore來(lái)忽略對某些文件的處理。

然后點(diǎn)擊output按鈕來(lái)選擇生成文檔的存放路徑和格式.

最后點(diǎn)擊create，phpdocumentor就會(huì )自動(dòng)開(kāi)始生成文檔了，最下方會(huì )顯示生成的進(jìn)度及狀態(tài)，如果成功，會(huì )顯示

Total Documentation Time: 1 seconds

done

Operation Completed!!

然后，我們就可以通過(guò)查看生成的文檔了，如果是pdf格式的，名字默認為documentation.pdf。

c. 試用phpdocumentor

下面我們就以pear中的phpunit2為例，演示一下如何使用phpdocumentor來(lái)生成文檔。

首先，把我們需要的參數確定下來(lái)：

-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開(kāi)始解析源文件并輸出工作信息。

命令運行完成后，我們的文檔就已經(jīng)生成好了。進(jìn)入我們指定的目標目錄，用瀏覽器打開(kāi)index.html就可以看見(jiàn)生成的文檔了。文檔界面由frame分成了三個(gè)部分，左上是包信息，左下是導航信息，右邊則是詳細的信息呈現頁(yè)。

索引、函數列表、類(lèi)列表、文件列表和子包。點(diǎn)擊上邊的class(es)鏈接，我們可以清晰的看見(jiàn)整個(gè)包的class tree。我們點(diǎn)擊其中一個(gè)class，就進(jìn)入了class的描述頁(yè)面。class描述頁(yè)面主要包含以下幾方面內容：

[描述：版權、作者、類(lèi)層次等]、[類(lèi)變量]、[類(lèi)常量]、[方法]、[繼承的變量]、[繼承的方法：非常有用的一個(gè)功能]

怎么樣，是不是很詳細呢？如果要生成chm，可以把前邊的-o參數改為"chm:default: default"，這樣phpdocumentor會(huì )為你生成好chm項目文件，只要用微軟的chm工具進(jìn)行編譯就可以得到可用的chm文件了。

d. 中文亂碼解決方法

如果注釋是中文的，需把 PhpDocumentor/phpDocumentor/Converters/* 中相應模板的語(yǔ)言標簽執行 iso-8859-1 到 utf-8 的替換，否則生成出來(lái)是亂碼。

4．給php代碼添加規范的注釋

PHPDocument是從你的源代碼的注釋中生成文檔，因此在給你的程序做注釋的過(guò)程，也就是你編制文檔的過(guò)程。從這一點(diǎn)上講，PHPdoc促使你要養成良好的編程習慣，盡量使用規范，清晰文字為你的程序做注釋?zhuān)瑫r(shí)多多少少也避免了事后編制文檔和文檔的更新不同步的一些問(wèn)題。在phpdocumentor中，注釋分為文檔性注釋和非文檔性注釋。所謂文檔性注釋?zhuān)悄切┓旁谔囟P(guān)鍵字前面的多行注釋?zhuān)囟P(guān)鍵字是指能夠被phpdoc分析的關(guān)鍵字，例如class，var等，具體的可參加附錄一。那些沒(méi)有在關(guān)鍵字前面或者不規范的注釋就稱(chēng)作非文檔性注釋?zhuān)@些注釋將不會(huì )被phpdoc所分析，也不會(huì )出現在你產(chǎn)生的api文當中。

如何書(shū)寫(xiě)文檔性注釋:

所有的文檔性注釋都是由/**開(kāi)始的一個(gè)多行注釋?zhuān)趐hpDocumentor里稱(chēng)為DocBlock,DocBlock是指軟件開(kāi)發(fā)人員編寫(xiě)的關(guān)于某個(gè)關(guān)鍵字的幫助信息，使得其他人能夠通過(guò)它知道這個(gè)關(guān)鍵字的具體用途，如何使用。 PhpDocumentor規定一個(gè)DocBlock包含如下信息：

1. 功能簡(jiǎn)述區

2. 詳細說(shuō)明區

3. 標記tag

文檔性注釋的第一行是功能描述區，正文一般是簡(jiǎn)明扼要地說(shuō)明這個(gè)類(lèi)，方法或者函數的功能，功能簡(jiǎn)述的正文在生成的文檔中將顯示在索引區。功能描述區的內容可以通過(guò)一個(gè)空行或者". "來(lái)結束。在功能描述區后是一個(gè)空行，接著(zhù)是詳細說(shuō)明區，這部分主要是詳細說(shuō)明你的API的功能、用途、如果可能也可以有用法舉例等等。在這部分，你應該著(zhù)重闡明你的API函數或者方法的通常的用途、用法，并且指明是否是跨平臺的（如果涉及到），對于和平臺相關(guān)的信息，你要和那些通用的信息區別對待。通常的做法是另起一行，然后寫(xiě)出在某個(gè)特定平臺上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者能夠編寫(xiě)相應的測試信息，比如邊界條件，參數范圍，斷點(diǎn)等等。之后同樣是一個(gè)空白行，然后是文檔的標記tag，指明一些技術(shù)上的信息，主要是調用參數類(lèi)型、返回值極其類(lèi)型、繼承關(guān)系、相關(guān)方法/函數等等。

關(guān)于文檔標記，詳細的請參考 -- 文檔標記。文檔注釋中還可以使用例如<b> <code>這樣的標簽，詳細介紹請參考附錄二。

下面是一個(gè)文檔注釋的例子

/**

* 函數add,實(shí)現兩個(gè)數的加法

*

* 一個(gè)簡(jiǎn)單的加法計算，函數接受兩個(gè)數a、b，返回他們的和c

*

* @param int 加數

* @param int 被加數

* @return integer

*/

function Add($a, $b)

{

return $a+$b;

}

生成文檔如下：

Add

integer Add( int $a, int $b)

[line 45]

函數add,實(shí)現兩個(gè)數的加法

Constants 一個(gè)簡(jiǎn)單的加法計算，函數接受兩個(gè)數a、b，返回他們的和c

Parameters

int $a - 加數

int $b - 被加數

5．文檔標記：

文檔標記的使用范圍是指該標記可以用來(lái)修飾的關(guān)鍵字，或其他文檔標記。所有的文檔標記都是在每一行的 * 后面以@開(kāi)頭。如果在一段話(huà)的中間出來(lái)@的標記，這個(gè)標記將會(huì )被當做普通內容而被忽略掉。

@access

使用范圍：class,function,var,define,module

該標記用于指明關(guān)鍵字的存取權限：private、public或proteced

@author

使用范圍：class，function，var，define，module，use

指明作者

@copyright

使用范圍：class，function，var，define，module，use

指明版權信息

@deprecated

使用范圍：class，function，var，define，module，constent，global，include

指明不用或者廢棄的關(guān)鍵字

@example

該標記用于解析一段文件內容，并將他們高亮顯示。PHPDOC 會(huì )試圖從該標記給的文件路徑 中讀取文件內容

@const

使用范圍：define

用來(lái)指明php中define的常量

@final

使用范圍：class,function,var

指明關(guān)鍵字是一個(gè)最終的類(lèi)、方法、屬性，禁止派生、修改。

@filesource

和example類(lèi)似，只不過(guò)該標記將直接讀取當前解析的php文件的內容并顯示。

@global

指明在此函數中引用的全局變量

@ingore

用于在文檔中忽略指定的關(guān)鍵字

@license

相當于html標簽中的<a>,首先是URL，接著(zhù)是要顯示的內容

例如<a >百度</a>

可以寫(xiě)作 @license http://www.baidu.com 百度

@link

類(lèi)似于license

但還可以通過(guò)link指到文檔中的任何一個(gè)關(guān)鍵字

@name

為關(guān)鍵字指定一個(gè)別名。

@package

使用范圍：頁(yè)面級別的 define，function，include

類(lèi)級別的 class，var，methods

用于邏輯上將一個(gè)或幾個(gè)關(guān)鍵字分到一組。

@abstrcut

說(shuō)明當前類(lèi)是一個(gè)抽象類(lèi)

@param

指明一個(gè)函數的參數

@return

指明一個(gè)方法或函數的返回指

@static

指明關(guān)建字是靜態(tài)的。

@var

指明變量類(lèi)型

@version

指明版本信息

@todo

指明應該改進(jìn)或沒(méi)有實(shí)現的地方

@throws

指明此函數可能拋出的錯誤異常，極其發(fā)生的情況

上面提到過(guò)，普通的文檔標記標記必須在每行的開(kāi)頭以@標記，除此之外，還有一種標記叫做inline tag,用{@}表示，具體包括以下幾種：

{@link}

用法同@link

{@source}

顯示一段函數或方法的內容

6．一些注釋規范

a.注釋必須是

/**

* XXXXXXX

*/

的形式

b.對于引用了全局變量的函數，必須使用glboal標記。

c.對于變量，必須用var標記其類(lèi)型（int,string,bool...）

d.函數必須通過(guò)param和return標記指明其參數和返回值

e.對于出現兩次或兩次以上的關(guān)鍵字，要通過(guò)ingore忽略掉多余的，只保留一個(gè)即可

f.調用了其他函數或類(lèi)的地方，要使用link或其他標記鏈接到相應的部分，便于文檔的閱讀。

g.必要的地方使用非文檔性注釋?zhuān)岣叽a易讀性。

h.描述性?xún)热荼M量簡(jiǎn)明扼要，盡可能使用短語(yǔ)而非句子。

i.全局變量，靜態(tài)變量和常量必須用相應標記說(shuō)明

7. 總結

編寫(xiě)文檔是一項乏味卻不得不做的工作，而編寫(xiě)API級的文檔更是意味著(zhù)大量的重復勞動(dòng)和難以保持的一致性。這里我們要推薦給大家的，是支持php5語(yǔ)法分析的文檔工具--phpDocumentor。phpDocumentor是一個(gè)非常強大的文檔自動(dòng)生成工具，利用它可以幫助我們編寫(xiě)規范的注釋?zhuān)梢子诶斫?，結構清晰的文檔，對我們的代碼升級、維護、移交等都有非常大的幫助。使用phpDocumentor不僅可以自動(dòng)從代碼中提取出函數和方法定義，還可以自動(dòng)處理各個(gè)class之間的關(guān)系，并據此生成class tree。你還可以選擇將文檔生成html、chm或者pdf。有了phpDocumentor，文檔工作變得輕松了很多。關(guān)于phpDocumentor更為詳細的說(shuō)明，可以到它的官方網(wǎng)站：http://manual.phpdoc.org/ 查閱。