PHPDocumentor是一個用PHP寫的工具，對於有規範注釋的php程式，它能夠快速生成具有相互參照，索引等功能的API文檔。Packageindex:這是按照模組來索引，Classtree:這是按照你的php類的繼承關係，可以生成一個樹狀的索引，Modulegroups:這是按照模組劃分Elementlist:這是你的所有元素（類，方法，過程/函式，變數）的字母順序的索引，phpDocumentor可以以不同的格式(包括HTML，XML和PDF)輸出文檔，由此進一步地減少了人工文檔化的時間。phpDocumentor已經是一款勝任的工具。
基本介紹
- 外文名：php Documentor
- 屬於：用PHP寫的工具
- 生成：一個樹狀的索引
- 含義：一款勝任的工具
簡介,結構及功能,PhpDocumentor基礎,注釋,文檔注釋,非文檔性注釋,文檔性注釋的書寫,文檔書寫指南,phpDocumentor關鍵字及文檔標誌,關鍵字,文檔標記,PhpDocumentor支持的常用標籤,
簡介
phpDocumentor是PEAR下面的一個非常優秀的模組，它的目標是實現類似javadoc的功能，可以為你的代碼快速生成具有相互參照,索引等功能的API文檔。
phpDocumentor生成的文檔和JAVADOC很相似，它有多種的索引方式：
Packageindex:這是按照模組來索引
Classtree:這是按照你的php類的繼承關係，可以生成一個樹狀的索引
Modulegroups:這是按照模組劃分
Elementlist:這是你的所有元素（類，方法，過程/函式，變數）的字母順序的索引
phpDocumentor可以以不同的格式(包括HTML，XML和PDF)輸出文檔，由此進一步地減少了人工文檔化的時間。當然，對於更為專業化的文檔，比如用戶手冊或者程式流框圖，你仍然需要懂得技術的人來編寫。但是對於比較簡單的文檔和方法原型，phpDocumentor已經是一款勝任的工具。
結構及功能
由於phpDocumentor本身也是符合pear的應用程式，我們首先了解一下它的結構。phpDocumentor是全部採用OOP的思想來編寫的，這也是PEAR所推薦的方式, phpDocumentor的工作原理：
phpDocumentor掃描指定目錄下面的php原始碼，掃描其中的關鍵字，截取需要分析的注釋，然後分析注釋中的專用的tag，生成xml檔案，接著根據已經分析完的類和模組的信息，建立相應的索引，生成xml檔案，對於生成的xml檔案，使用定製的模板輸出為html檔案。
從設計上來說，phpDocumentor使用了2個超類：PhpDocumentorObject和PhpDocumentorError。這是整個phpDocumentor的基本類，這種方式也是PEAR所推薦的，也就是說當你編寫你自己的套用框架的時候，最好能夠有一個基本的超類，而其他的子類或者是功能類都有一個共同的祖先。在掃描原始碼過程中，phpDocumentor使用的是類似GREP的形式，並沒有象我們通常想的那樣，使用正則表達式來實現，根據作者的解釋，他曾經嘗試過使用正則表達式，但是資源的占用和處理速度都很難令人滿意，因此採用了這種非常規的形式，具體的實現有興趣的讀者可以參看原始碼。我認為phpDocumentor令人滿意的另一方面是其分析結果是以XML形式保存的，這樣就意味著其他的應用程式很容易可以共享這個數據，同時PhpDocumentor也提供了相應的接口，你可以實現這個接口，把API文檔生成其他的形式，比如PDF，LATEX，WORD等等。目前，phpDocumentor的分析結果可以以HTML形式表現，以後可能會有更多的形式。即使是HTML形式，由於使用了模板機制（他使用了PEAR的IT和ITX模組來實現），你可以很方便地定製成你自己需要的風格，
作為“PHP的完整文檔化方案”，phpDocumentor以讀取原始碼的註解並使用這些註解建立一個專業化的簡潔的API文檔。這一工具支持不同的輸出格式：HTML，PDF，Windows HLP，以及XML。在每一這些輸出格式中，可以使用到不同的模板和設計風格。並且你甚至可以建立你自己的模板——phpDocumentor使用這一著名的Smarty template引擎來運算元據。
PhpDocumentor基礎
PhpDocumentor可以通過PEAR獲得，PHP Extension 以及 Application Repository可以從PhpDocumentor.org中下載。在pear下安裝phpDocumentor是一件極其簡單的事情，只需要在cmd視窗中cd 到php安裝目錄下，然後輸入Pear install phpDocumentor Pear就會自己下載並完成phpDocumentor的安裝。在phpDocumentor成功安裝後，php安裝目錄下會多出來一個phpDocumentor.bat。這個檔案就是我們用來生成文檔的批處理檔案了。在phpDocumentor.bat所在目錄下，輸入PhpDocumentor –h 會得到一個phpDocumentor的詳細參數列表：
-f 要進行分析的檔案名稱，多個檔案用逗號分割
-d 要分析的目錄，多個目錄用逗號分割
-t 生成的文檔的存放路徑
-o 輸出的文檔格式，結構為輸出格式:轉換器名:模版目錄，例如：HTML:frameshpedit（其他的命令請大家閱讀help的提示信息）。
注釋
PhpDocumentor是從你的原始碼的注釋中生成文檔，因此在給你的程式做注釋的過程，也就是你編制文檔的過程。從這一點上講，PhpDocumentor促使你要養成良好的編程習慣，儘量使用規範，清晰文字為你的程式做注釋，同時多多少少也避免了事後編制文檔和文檔的更新不同步的一些問題。編制符合PhpDocumentor規範的注釋是非常重要的，掌握了這一點，基本上就可以利用PhpDocumentor為你工作了。
注釋在PhpDocumentor中分為文檔注釋和非文檔注釋
文檔注釋
文檔注釋實際上是一些特殊形式的多行注釋，一般是放在你需要注釋的特定的關鍵字(這些關鍵字是指將會被phpDocumentor分析的那些關鍵字，相關的關鍵字列表請參看後面第4節的說明）前面。下面是一個文檔注釋的例子：
/**
* Common base class of all phpDocumentor classes （簡述，用在索引列表中）
*
* As a kind of common base class PhpDocumentorObject holds
* configuration values (e.g. error handling) and debugging
* methods (e.g. introspection()). It does not have a constructor,
* so you can always inheritig PhpDocumentor classes from this
* class without any trouble. （詳細的功能描述）
*
* @author Ulf Wendel
* @version $Id: PhpDocumentorObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
* @package PhpDocumentor （文檔標記）
*/
class PhpDocumentorObject {
.....
}
以上的文檔注釋將會生成如下的文檔：
<b>PhpDocumentorObject</b>
PhpDocumentorObject
Common base class of all phpDocumentor classes
<b>private class PhpDocumentorObject </b>
Common base class of all phpDocumentor classes
As a kind of common base class PhpDocumentorObject holdsconfiguration values (e.g. error
handling) and debuggingmethods (e.g. introspection()). It does not have a
constructor,so you can always inheritig PhpDocumentor classes from thisclass without any trouble.
Authors Ulf Wendel <[email protected]>
Version $Id: PhpDocumentorObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
非文檔性注釋
如果你的注釋沒有放在那些phpDocumentor指定的關鍵字前面，那么phpDocumentor認為你所作的這些注釋是屬於非文檔注釋，將不會被phpDocumentor所分析，也不會出現在你產生的api文當中。
文檔性注釋的書寫
從上文 我們可以看到，一個文檔性的注釋，是由3個部分組成的，分別是：功能簡述區，功能詳細說明區，文檔標記區。
首先，第一行是一個注釋開始的標誌"/**"，然後是回車，從第2行開始就是功能簡述區，功能簡述區是以縮進的"*"開始的，在簡述的正文和這個"*"號之間用空格分隔（注意，在文檔中，都是以*開始，並且這些*保持對齊的縮進格式）。功能簡述的正文一般是簡明扼要地說明這個類，方法或者函式的功能，功能簡述的正文在生成的文檔中將顯示在索引區。
在功能簡述區後面是一個空的注釋行，用來分割簡述區和詳細說明區。功能詳細說明區也是以縮進的'*"來引導的，這部分主要是詳細說明你的API的功能，用途，如果可能，也可以有用法舉例等等。在這部分，你應該著重闡明你的API函式或者方法的通常的用途，用法，並且指明是否是跨平台的（如果涉及到），對於和平台相關的信息，你要和那些通用的信息區別對待，通常的做法是另起一行，然後寫出在某個特定平台上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者能夠編寫相應的測試信息，比如邊界條件，參數範圍，斷點等等。
在功能詳細說明區後面，是空白的注釋行，然後是文檔標記區，你可以在這些書寫相關的文檔標記（這些文檔標記的用法請參考後面的第4節），指明一些技術上的細節信息，最主要的是調用參數類型，返回值及其類型，繼承關係，相關方法/函式等等。多個文檔標記應該使用相同的縮進，組成一個"標記塊"，便於閱讀和分析。
在文檔標記區下面的一行就是注釋結束行"*/",注意，在注釋結束標記*/後面應該直接跟一個回車，不要另外附加其他的東西，否則可能造成phpDocumentor分析出錯。
以上就是書寫一個文檔性注釋的基本方法，下面我們討論一下書寫文檔時的規範和技巧。
文檔書寫指南
在你描述你的代碼的用途或者是功能的時候，最好能夠遵循大多數人的習慣，通俗地講就是"你告訴我的信息正是我想要知道的"。為此，這裡將介紹一些書寫文檔注釋的技巧和規範，希望能夠對你有所幫助：
使用 <code> 來標誌關鍵字和命名及相關的代碼。如果在文檔中需要引用一些關鍵字，變數名，或者是你要給出一些代碼的例子，那么你最好使用<code></code>來將這些關鍵字，變數名，代碼片段和你的文檔分隔開，這樣，讀者閱讀的時候，將會知道，這些將是運行的代碼，關鍵字而不是你的描述性的語言。
使用簡單，明確的語言，避免冗長，複雜，晦澀的長句來描述。尤其是在功能簡述，參數說明等索引部分中，儘量使用簡單明白的語言揭示主要的信息，把其他的細節放在詳細說明部分去闡述。如果你使用英語，建議使用短語而不一定是句子。
如果使用英語，建議使用第3人稱單數的形式來說明，在給方法、函式說明的時候，你需要說明的是這個方法"作了什麼"，而不是"怎么做"。因此，建議你的說明是以動詞開始，比如"返回記錄數"，"刪除給定的記錄"等等。
當你引用的某個對象或者變數是從當前的類中建立的，那么使用 "this" 代替 "the" 來指代那個對象或者是變數 避免空話，廢話，對於你所要給出的API，在你的API後面要有它的功能描述，是其能夠"自成文檔"。所謂的空話，廢話是指，你的描述不是功能描述，而只是API名稱的簡單重複和羅列，或者是用另一個API來解釋這個API，到頭來，你的讀者也不知道你所要表達的內容實質。你的描述，應該是那些從你的類名，方法名，或者是函式名看不到的補充的信息，而不是把你的API名稱再重複一遍。很多人可能很多人（包括我）不知不覺中就犯了這個錯誤，下面是一個例子：
/**
* 設定用戶記錄集
*
* @param text 給定的表名
*/
function set_user_record($table) {
你從上面這段注釋中能夠知道什麼？因此，這段注釋實際上是廢話，因為你從函式名稱上是可以看出的，下面是改進後的：
/**
* 打開系統用戶表並設定為當前用戶記錄集，此記錄集將用於隨後相關用戶數據更新操作的預設記錄集。如果失敗則拋出一個資料庫錯誤。
*
* @param text 要打開的系統用戶表的表名。
*/
function set_user_record($table) {
適當地使用連結，為你文檔中引用的API名稱（包括你的其他類及方法，PHP的函式等）添加適當的連結是很受歡迎的：你可以使用@link標記來添加到相關的API的連結，不過，你沒有必要為文檔中引用的所有的API都添加連線，這樣會很不美觀，這裡有一個簡單的標準：如果用戶在這個地方看到某個API，確實希望要去點擊以便獲取更多信息，這樣有助於他們去理解你的文檔，並且即使添加了連結，只在它第一出現的是時候添加，沒有必要重複添加相同的LINK。
由於phpDocumentor的功能限制，一個PHP檔案只定義一個類或模組，不要把類和模組的定義放在同一個檔案里，否則phpDocumentor可能無法工作，至少目前版本是這樣。如果你的框架使用OOP來構建，應避免同時使用模組或模組組；同時應該仔細規劃你的套用結構，你的套用框架應該是一個類似樹型的結構，頂層的分支不要太多，例如你可以設計2個超類，分別是作為正常套用和錯誤處理的超類，其餘的都從這2個類派生出來。
phpDocumentor關鍵字及文檔標誌
關鍵字
class 、function 、var 、include (include_once, require, require_once) 、define
在以上這些關鍵字前面所做的注釋，都被認為是文檔性注釋。
文檔標記
說明：使用範圍是指該標記可以用來修飾的關鍵字，或其他文檔標記@abstract 使用範圍：class, function, var 說明當前類是一個抽象類。
注釋：從PHP語言角度來說，它並不象JAVA，C++那樣，支持抽象類這個概念。也沒有相應的關鍵字來修飾某個類是抽象類。由於phpDocumentor實際上大部分是借鑑了JAVADOC的做法，因此很多文檔標記也是直接從JAVADOC中沿襲過來，如abstract,access,final等等。雖然這些特性沒有從語言級別得到支持，不過從使用者角度來遵循這些特性，仍是值得推薦的。
舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
*/
class paint_start {
/**
* 繪製數量
* @abstract
*/
var $number;
/**
* 繪製五星圖案
* @abstract
*/
function paint() {
;
}
}
@access (public|private) 使用範圍：class, function, var, define, module
指明這個變數、類、函式/方法的存取許可權。如果你的函式是內部使用，你應該指明它為private,這樣的好處是，即使PHP不能阻止其他的人使用你的私有數據，但是至少你向你的用戶傳達這樣的信息，這是一個私有的函式，因此不保證在將來的版本中仍存在；對於使用者而言，表示為@private的數據和方法，你不應該直接使用，即使你可以這樣做。
舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
* @access public
*/
class paint_start {
/**
* 繪製數量
* @abstract
* @access private
*/
var $number;
/**
* 繪製五星圖案
* @abstract
* @access public
*/
function paint() {
;
}
}
@author Name [<email>] [, ...] 使用範圍：class, function, var, define, module, use 指明作者信息,依次是作者姓名，email地址，其他的通訊信息。如果有多個作者，按照其先後次序，使用多個@author依次列出：
* @author Night Sailer <[email protected]>
* @author Lee Tester <[email protected]>
@brother (function()|$variable) 使用範圍：class, function, var, define, module, use
@sister (function()|$variable) 使用範圍：class, function, var, define, module, use
指出兄弟類、函式或者是變數.這些函式、類、變數等有相似的信息和並實現相同的功能。比如，調用和返回的參數的個數和類型相同，實現的功能也一樣。這種情況，你可以使用@brother 或者 @sister指明它的兄弟函式，無須在重複書寫函式的功能等信息了。
舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
* @access public
*/
class paint_start {
/**
* 繪製數量
* @abstract
* @access private
*/
var $number;
/**
* 繪製五星圖案
* @abstract
* @access public
*/
function paint() {
;
}
/**
* @brother paint()
*/
function draw() {
;
}
}
@const[ant] label [description] 使用範圍：define 指明常量
這個標記實際上是用來說明php的define關鍵字定義的常量。
@copyright description 使用範圍：class, function, var, module, define, use 指明版權資訊。
@deprec[ated] label 使用範圍：class, function, var, module, define, use指明不推薦或者是廢棄的信息.
如果你的某個函式或者方法，已經被新的函式方法替代，或者是已經廢棄，不希望讀者繼續使用。那么你可以使用這個標誌告訴讀者，這個函式只是為了保持兼容性而保留的，它不被推薦使用，如果它已經被其他函式替代，也要指出這個替代者。
例子：
/**
* 過時的類
*
* @deprec 1.5-2000/12/06
* @access public
*/
function dontUseMeAnyMore() {
print "Don't use me any more. I have been deprecated.";
}
@exclude label 使用範圍：class, function, var, module, define, use 指明當前的注釋將不進行分析，不出現在文擋中
@final 使用範圍：class, function, var 指明這是一個最終的類、方法、屬性，禁止派生、修改。
舉例：
/**
* 圓周率
* @final
*/
var $PI = 3.1415926;
@global (object objecttype|type) [$varname] [description] 使用範圍：function 指明在此函式中引用的全局變數
舉例：
/**
* Simuliert include_once in PHP 3.
*
* @global array $__used_files 已經include的檔案列表
* @access public
*/
function include_once($filename) {
global $__used_files;
if (!isset($__used_files["include_once"][$filename])) {
$__used_files["include_once"][$filename] = true;
include($filename);
}
}
@include description 使用範圍：use 指明包含的檔案的信息。
舉例：
/**
* 抽象繪圖類的定義.
*
* @include Function: _require_
*/
require("abstract.php");
@link URL description 使用範圍：class, function, var, module, define, use 定義線上連線，如上面3.4中講到的，你可以使用@link添加適當的線上連結。
例如：@link http://www.phpDocumentor.de/ PhpDocumentor Home
@magic description 這個標記在phpDocumentor中沒有說明，具體用法現在仍不清楚
@module label 使用範圍：module 定義歸屬的模組信息，label是模組的名字，擁有相同的模組名字的函式在索引分類中將被組合在一起。如果你沒有使用OOP的思想來編寫PEAR代碼，那么建議你使用這個標記把相關的函式歸集到相應的模組下面，這樣你的整體的框架不至於過於零散和混亂。
@modulegroup label 使用範圍：module 定義歸屬的模組組 label是這個模組組的名字，如果你的應用程式的模組很多，你可以把不同的模組按照邏輯功能的不同，劃分成相應的模組組，這樣，你的套用框架可以有比較清晰的邏輯關係。這是對於沒有使用OOP編程的來說的，如果使用OOP的思想，沒有必要使用模組組的概念，因為直接使用"包-超類--基類--子類"的形式來體現你的框架結構要比使用"包-模組組-模組"的形式好的多。
@package label 使用範圍：class, module 定義歸屬的包的信息,label 是這個包的名字。相同的包的名字的類在最終文檔索引中將被分在一起。實際上，包還可以理解為不同的名字空間，雖然PHP沒有名字空間的概念，但是你可以把相關的類、模組都歸屬於同一個包，這樣，相當於組織了一個名字空間，當然，你的套用框架可能會有不同的包，可惜的是，這種情況下從語法上是得不到名字空間這種保證的，你只能通過人為地去避免不同的包的函式或者類重名。
@param[eter] (object objecttype|type) [$varname] [description] 使用範圍：function 定義函式或者方法的參數信息。這是最常使用的文檔標記了。
ojecttype 是對象的類名，type 指出這個參數的類型，它可以是下列類型：
string 該參數是一個字元型變數。
array 該參數是一個數組。
integer 該參數是一個數值型。
integer (octal) 該參數是一個數值型，並且是按照八進制方式存放。
integer (hexadecimal) 該參數是一個數值型，並且是按照十六進制方式存放。
boolean 該參數是一個布爾型。
mixed 該參數的類型是可變的，可以上面幾種類型的組合。不過，在隨後的說明中一般要說明可以接受的變數的類型。
$varname 是形參的名稱
[description] 是對於參數的說明。
如果函式接受的是多個參數，那么要按照從左到右，依次用@param對齊列出，如下面所示：
*
* @param array $tags array of tags returned by getTags
* @param array $data array where the allowed tags and their values are copied to
* @param array $allowed array of allowed (recognized) tags
@return (object objecttype|type) [$varname] 使用範圍：function 定義函式或者方法的返回信息。
返回信息的類型同@param一樣，$varname是返回變數的名稱，可有可無。不同的是@return只有一個，不會出現多個@return
@see (function()|$varname|((module|class):(function()|$varname)) [, ...] 使用範圍：class, function, var, module, define, use 定義需要參考的函式、變數，並加入相應的超級連線。這也是較常用的標記。對於相關的函式，變數，你可以使用@see來增加一個到相關函式和變數的連結。多個相關的函式、變數寫在一行，中間用逗號來分隔。
參考的函式、變數如果是當前類或模組的，那么你可以直接寫函式、或者變數的名，如果是函式那么要在函式名後面加上括弧（），變數名要加上$。需要注意的，這裡所謂的變數名也應該是你用@var來說明過的，否則，phpDocumentor將無法找到相關的參照而報錯。
如果你想引用其他類或者其他模組的函式或者是變數，那么，你可以在函式名、變數名前面加上類或模組的名字作為範圍指示，中間用：：來分隔。
下面是一些例子：
@see $run_time,$idle_time,$begin_time,$end_time
@see getRuntime(), getIdletime(),getBegintime(),getEndtime()
@see TIME::$run_time, TIME::getBegintime()
@since label 使用範圍： class, function, var, module, define, use
指明該api函式或者方法是從哪個版本開始引入的。
@throws exception [, exception] 使用範圍： function 指明此函式可能拋出的錯誤異常,極其發生的情況 如果你預料到在這個函式中有產生異常的條件，那么你可以使用@throws標記來說明這些異常是什麼，什麼情況下產生異常。比如，讀取磁碟檔案出錯，無法連線資料庫，網路連線逾時或者是在一些情況下，你"故意"拋出的異常等等。
@todo 使用範圍：class, function, module, use 指明應該改進或沒有實現的地方
@var (object objecttype|type) [$varname] [description] 使用範圍：var 定義說明變數/屬性。
object objecttype|type 定義你的變數的類型，同@param一樣
$varname 該變數的名字，你可以從其他地方使用@see來引用這個名字
description 對變數的描述
@version label 使用範圍：class, function, module, use 定義版本信息.
你當然可以自己手工寫這些版本信息，不過PEAR推薦你使用CVS的$Id標記來自動標示你的版本信息。形式如下：
@version $Id 這樣，當你checkout的時候，CVS自動會擴展成： @version $Id: PhpDocumentorParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp
PhpDocumentor標記的基本元素名為DocBlock，即一個多行註解塊，它可以出現在任何PHP construct，類，或者函式之前，如下所示：
/**
* text here
*
*/
在這一DocBlock之中，PhpDocumentor接收三種類型的選項：一個簡短描述，一個比較長的描述，以及一系列以@符號前綴的特定標籤。這些標籤為可選擇性，然而它能夠使最終文檔變得更加精確。
當你開始這類自動文檔系統使用時，我希望這篇文章能夠給你帶來幫助。但這只是冰山之一角，你還可以將PhpDocumentor套用到其它很多地方，你可以在excellent online tutorial(最為出色的線上使用指南)得到所有的信息。我希望你能夠充分地利用PhpDocumentor的強大功能，在以後的PHP程式中節省時間和減輕壓力。
PhpDocumentor支持的常用標籤
@abstract 申明變數/類/方法
@access指明這個變數、類、函式/方法的存取許可權
@author 函式作者的名字和信箱地址
@category 組織packages
@copyright指明版權資訊
@const指明常量
@deprecate指明不推薦或者是廢棄的信息
@example 示例
@exclude指明當前的注釋將不進行分析，不出現在文擋中
@final指明這是一個最終的類、方法、屬性，禁止派生、修改。
@global指明在此函式中引用的全局變數
@include指明包含的檔案的信息
@link定義線上連線
@module定義歸屬的模組信息
@modulegroup定義歸屬的模組組
@package定義歸屬的包的信息
@param定義函式或者方法的參數信息
@return定義函式或者方法的返回信息
@see定義需要參考的函式、變數，並加入相應的超級連線。
@since 指明該api函式或者方法是從哪個版本開始引入的
@static 指明變數、類、函式是靜態的。
@throws指明此函式可能拋出的錯誤異常,極其發生的情況
@todo指明應該改進或沒有實現的地方
@var定義說明變數/屬性。
@version定義版本信息
