對于一個開發(fā)人員，文檔總是最感到頭疼的事情之一。而且，很可能你對待文檔會采取截然不同的2種態(tài)度：

當你使用別人的代碼庫的時候，最希望得到的是它的技術文檔，尤其是當時間很緊，而你又不得不硬著頭皮去讀那些生澀的代碼的時候。

當寫你自己的程序的時候，最不希望做的事情卻是給它編寫專門的技術文檔，你會以種種理由給自己開脫：我的代碼已經(jīng)足夠清晰了，完全不用再為它重新編寫文檔了……

也許是為了緩解這種矛盾，有很多工具可以幫助你，通過從源代碼中抽取相應的注釋，可以自動生成相應的api文檔。java中的javadoc,perl中的pod2man。相比之下，php以前似乎缺乏相應的工具，不過，隨著phpdoc的不斷完善，這種局面已經(jīng)大大改觀。

在第一篇pear的編碼規(guī)則中有一條，pear程序中的注釋應該能夠被phpdoc轉換。由此可見，phpdoc在pear中的作用可不小。今天，我們將詳細討論phpdoc，這個優(yōu)秀的pear程序。

1. 什么是phpdoc
PHPDoc是PEAR下面的一個非常優(yōu)秀的模塊，它的目標是實現(xiàn)類似javadoc的功能，可以為你的代碼快速生成具有相互參照,索引等功能的API文檔。如果你使用過javadoc生成的文檔(如jdk的文檔），你會非常清楚，如果你沒有用過，那么下面是一個phpdoc生成它自己的文檔頁面的截圖：






從圖上可以知道，phpdoc生成的文檔和JAVADOC很相似，它有多種的索引方式：
Packageindex:這是按照模塊來索引
Classtree:這是按照你的php類的繼承關系，可以生成一個樹狀的索引
Modulegroups:這是按照模塊劃分
Elementlist:這是你的所有元素（類，方法，過程/函數(shù)，變量）的字母順序的索引

2. phpdoc的結構及功能
由于phpdoc本身也是符合pear的應用程序，我們首先了解一下它的結構。phpdoc是全部采用OOP的思想來編寫的，這也是PEAR所推薦的方式,phpdoc的工作原理：

phpdoc掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取需要分析的注釋，然后分析注釋中的專用的tag，生成xml文件，接著根據(jù)已經(jīng)分析完的類和模塊的信息，建立相應的索引，生成xml文件
對于生成的xml文件，使用定制的模板輸出為html文件。

從設計上來說，phpdoc使用了2個超類：PhpdocObject和PhpdocError。這是整個PHPDOC的基本類，這種方式也是PEAR所推薦的，也就是說當你編寫你自己的應用框架的時候，最好能夠有一個基本的超類，而其他的子類或者是功能類都有一個共同的祖先。在掃描源代碼過程中，PHPDOC使用的是類似GREP的形式，并沒有象我們通常想的那樣，使用正則表達式來實現(xiàn)，根據(jù)作者的解釋，他曾經(jīng)嘗試過使用正則表達式，但是資源的占用和處理速度都很難令人滿意，因此采用了這種非常規(guī)的形式，具體的實現(xiàn)有興趣的讀者可以參看源代碼。我認為PHPDOC令人滿意的另一方面是其分析結果是以XML形式保存的，這樣就意味著其他的應用程序很容易可以共享這個數(shù)據(jù)，同時PHPDCO也提供了相應的接口，你可以實現(xiàn)這個接口，把API文檔生成其他的形式，比如PDF，LATEX，WORD等等。目前，PHPDOC的分析結果可以以HTML形式表現(xiàn)，以后可能會有更多的形式。即使是HTML形式，由于使用了模板機制（他使用了PEAR的IT和ITX模塊來實現(xiàn)），你可以很方便地定制成你自己需要的風格，

3. PHPDoc基礎
PHPDoc是從你的源代碼的注釋中生成文檔，因此在給你的程序做注釋的過程，也就是你編制文檔的過程。

從這一點上講，PHPdoc促使你要養(yǎng)成良好的編程習慣，盡量使用規(guī)范，清晰文字為你的程序做注釋，同時多多少少也避免了事后編制文檔和文檔的更新不同步的一些問題。

編制符合PHPDoc規(guī)范的注釋是非常重要的，掌握了這一點，基本上就可以利用PHPDoc為你工作了。

注釋在PHPDoc中分為文檔注釋和非文檔注釋

3.1 文檔注釋
文檔注釋實際上是一些特殊形式的多行注釋，一般是放在你需要注釋的特定的關鍵字(這些關鍵字是指將會被phpdoc分析的那些關鍵字，相關的關鍵字列表請參看后面第4節(jié)的說明）前面。下面是一個文檔注釋的例子：


/**
* Common base class of all phpdoc classes （簡述，用在索引列表中）
*
* As a kind of common base class PhpdocObject holds
* configuration values (e.g. error handling) and debugging
* methods (e.g. introspection()). It does not have a constructor,
* so you can always inheritig Phpdoc classes from this
* class without any trouble. （詳細的功能描述）
*
* @author Ulf Wendel
* @version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
* @package PHPDoc （文檔標記）
*/
class PhpdocObject {
.....
}



以上的文檔注釋將會生成如下的文檔：
<b>PhpdocObject</b>

PhpdocObject

Common base class of all phpdoc classes


<b>private class PhpdocObject </b>

Common base class of all phpdoc classes
As a kind of common base class PhpdocObject holdsconfiguration values (e.g. error
handling) and debuggingmethods (e.g. introspection()). It does not have a
constructor,so you can always inheritig Phpdoc classes from thisclass without any trouble.

Authors Ulf Wendel <ulf.wendel@phpdoc.de>
Version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $




3.2 非文檔性注釋
如果你的注釋沒有放在那些phpdoc指定的關鍵字前面，那么phpdoc認為你所作的這些注釋是屬于非文檔注釋，將不會被phpdoc所分析，也不會出現(xiàn)在你產生的api文當中。

3.3 如何書寫你的文檔性注釋
從3.1 我們可以看到，一個文檔性的注釋，是由3個部分組成的，分別是：功能簡述區(qū)，功能詳細說明區(qū)，文檔標記區(qū)。

首先，第一行是一個注釋開始的標志"/**"，然后是回車，從第2行開始就是功能簡述區(qū)，功能簡述區(qū)是以縮進的"*"開始的，在簡述的正文和這個"*"號之間用空格分隔（注意，在文檔中，都是以*開始，并且這些*保持對齊的縮進格式）。功能簡述的正文一般是簡明扼要地說明這個類，方法或者函數(shù)的功能，功能簡述的正文在生成的文檔中將顯示在索引區(qū)。

在功能簡述區(qū)后面是一個空的注釋行，用來分割簡述區(qū)和詳細說明區(qū)。功能詳細說明區(qū)也是以縮進的'*"來引導的，這部分主要是詳細說明你的API的功能，用途，如果可能，也可以有用法舉例等等。在這部分，你應該著重闡明你的API函數(shù)或者方法的通常的用途，用法，并且指明是否是跨平臺的（如果涉及到），對于和平臺相關的信息，你要和那些通用的信息區(qū)別對待，通常的做法是另起一行，然后寫出在某個特定平臺上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者能夠編寫相應的測試信息，比如邊界條件，參數(shù)范圍，斷點等等。

在功能詳細說明區(qū)后面，是空白的注釋行，然后是文檔標記區(qū)，你可以在這些書寫相關的文檔標記（這些文檔標記的用法請參考后面的第4節(jié)），指明一些技術上的細節(jié)信息，最主要的是調用參數(shù)類型，返回值極其類型，繼承關系，相關方法/函數(shù)等等。多個文檔標記應該使用相同的縮進，組成一個"標記塊"，便于閱讀和分析。

在文檔標記區(qū)下面的一行就是注釋結束行"*/",注意，在注釋結束標記*/后面應該直接跟一個回車，不要另外附加其他的東西，否則可能造成PHPDOC分析出錯。

以上就是書寫一個文檔性注釋的基本方法，下面我們討論一下書寫文檔時的規(guī)范和技巧。

3.4 文檔書寫指南
在你描述你的代碼的用途或者是功能的時候，最好能夠遵循大多數(shù)人的習慣，通俗地講就是"你告訴我的信息正是我想要知道的"。為此，這里將介紹一些書寫文檔注釋的技巧和規(guī)范，希望能夠對你有所幫助：

使用 <code> 來標志關鍵字和命名及相關的代碼。如果在文檔中需要引用一些關鍵字，變量名，或者是你要給出一些代碼的例子，那么你最好使用<code></code>來將這些關鍵字，變量名，代碼片段和你的文檔分隔開，這樣，讀者閱讀的時候，將會知道，這些將是運行的代碼，關鍵字而不是你的描述性的語言。
使用簡單，明確的語言，避免冗長，復雜，晦澀的長句來描述。尤其是在功能簡述，參數(shù)說明等索引部分中，盡量使用簡單明白的語言揭示主要的信息，把其他的細節(jié)放在詳細說明部分去闡述。如果你使用英語，建議使用短語而不一定是句子。
如果使用英語，建議使用第3人稱單數(shù)的形式來說明
在給方法，函數(shù)說明的時候，你需要說明的是這個方法"作了什么"，而不是"怎么做"。因此，建議你的說明是以動詞開始，比如"返回記錄數(shù)"，"刪除給定的記錄"等等。
當你引用的某個對象或者變量是從當前的類中建立的，那么使用 "this" 代替 "the" 來指代那個對象或者是變量
避免空話，廢話，對于你所要給出的API，在你的API后面要有它的功能描述，是其能夠"自成文檔"。所謂的空話，廢話是指，你的描述不是功能描述，而只是API名稱的簡單重復和羅列，或者是用另一個API來解釋這個API，到頭來，你的讀者也不知道你所要表達的內容實質。你的描述，應該是那些從你的類名，方法名，或者是函數(shù)名看不到的補充的信息，而不是把你的API名稱再重復一遍。很多人可能很多人（包括我）不知不覺中就犯了這個錯誤，下面是一個例子：
/**
* 設置用戶記錄集
*
* @param text 給定的表名
*/
function set_user_record($table) {




你從上面這段注釋中能夠知道什么？因此，這段注釋實際上是廢話，因為你從函數(shù)名稱上是可以看出的，下面是改進后的：
/**
* 打開系統(tǒng)用戶表并設置為當前用戶記錄集，此記錄集將用于隨后相關用戶數(shù)據(jù)更新操作的缺省記錄集。如果失敗則拋出一個數(shù)據(jù)庫錯誤。
*
* @param text 要打開的系統(tǒng)用戶表的表名。
*/
function set_user_record($table) {




適當?shù)厥褂面溄�。為你文檔中引用的API名稱（包括你的其他類及方法，PHP的函數(shù)等）添加適當?shù)逆溄邮呛苁軞g迎的：你可以使用@link標記來添加到相關的API的鏈接，不過，你沒有必要為文檔中引用的所有的API都添加連接，這樣會很不美觀，這里有一個簡單的標準：如果用戶在這個地方看到某個API，確實希望要去點擊以便獲取更多信息，這樣有助于他們去理解你的文檔，并且即使添加了鏈接，只在它第一出現(xiàn)的是時候添加，沒有必要重復添加相同的LINK。
由于PHPDOC的功能限制，一個PHP文件只定義一個類或模塊，不要把類和模塊的定義放在同一個文件里，否則PHPDOC可能無法工作，至少目前版本是這樣。如果你的框架使用OOP來構建，應避免同時使用模塊或模塊組；同時應該仔細規(guī)劃你的應用結構，你的應用框架應該是一個類似樹型的結構，頂層的分支不要太多，例如你可以設計2個超類，分別是作為正常應用和錯誤處理的超類，其余的都從這2個類派生出來。
4. PHPDoc關鍵字及文檔標志
4.1 關鍵字
class 、function 、var 、include (include_once, require, require_once) 、define

在以上這些關鍵字前面所做的注釋，都被認為是文檔性注釋。

4.2 文檔標記
說明：使用范圍是指該標記可以用來修飾的關鍵字，或其他文檔標記
@abstract 使用范圍：class, function, var
說明當前類是一個抽象類。

注釋：從PHP語言角度來說，它并不象JAVA，C++那樣，支持抽象類這個概念。也沒有相應的關鍵字來修飾某個類是抽象類。由于PHPDOC實際上大部分是借鑒了JAVADOC的做法，因此很多文檔標記也是直接從JAVADOC中沿襲過來，如abstract,access,final等等。雖然這些特性沒有從語言級別得到支持，不過從使用者角度來遵循這些特性，仍是值得推薦的。

舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
*/
class paint_start {
/**
* 繪制數(shù)量
* @abstract
*/
var $number;
/**
* 繪制五星圖案
* @abstract
*/
function paint() {
;
}
}


@access (public private) 使用范圍：class, function, var, define, module

指明這個變量、類、函數(shù)/方法的存取權限。如果你的函數(shù)是內部使用，你應該指明它為private,這樣的好處是，即使PHP不能阻止其他的人使用你的私有數(shù)據(jù)，但是至少你向你的用戶傳達這樣的信息，這是一個私有的函數(shù)，因此不保證在將來的版本中仍存在；對于使用者而言，表示為@private的數(shù)據(jù)和方法，你不應該直接使用，即使你可以這樣做。

舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
* @access public
*/
class paint_start {

/**
* 繪制數(shù)量
* @abstract
* @access private
*/
var $number;

/**
* 繪制五星圖案
* @abstract
* @access public
*/
function paint() {
;
}

}


@author Name [<email>] [, ...] 使用范圍：class, function, var, define, module, use

指明作者信息,依次是作者姓名，email地址，其他的通訊信息。如果有多個作者，按照其先后次序，使用多個@author依次列出：

* @author Night Sailer <night@hotmail.com>
* @author Lee Tester <tester@gnome.org>
@brother (function() $variable) 使用范圍：class, function, var, define, module, use
@sister (function() $variable) 使用范圍：class, function, var, define, module, use

指出兄弟類、函數(shù)或者是變量.這些函數(shù)、類、變量等有相似的信息和并實現(xiàn)相同的功能。比如，調用和返回的參數(shù)的個數(shù)和類型相同，實現(xiàn)的功能也一樣。這種情況，你可以使用@brother 或者 @sister指明它的兄弟函數(shù)，無須在重復書寫函數(shù)的功能等信息了。

舉例：
/**
* 這是一個繪五星圖案的抽象類.
* @abstract
* @access public
*/
class paint_start {

/**
* 繪制數(shù)量
* @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
指明不推薦或者是廢棄的信息.

如果你的某個函數(shù)或者方法，已經(jīng)被新的函數(shù)方法替代，或者是已經(jīng)廢棄，不希望讀者繼續(xù)使用。那么你可以使用這個標志告訴讀者，這個函數(shù)只是為了保持兼容性而保留的，它不被推薦使用，如果它已經(jīng)被其他函數(shù)替代，也要指出這個替代者。

例子：
/**
* 過時的類
*
* @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
指明當前的注釋將不進行分析，不出現(xiàn)在文擋中

@final 使用范圍：class, function, var
指明這是一個最終的類、方法、屬性，禁止派生、修改。
舉例：
/**
* 圓周率
* @final
*/
var $PI = 3.1415926;




@global (object objecttype type) [$varname] [description] 使用范圍：function
指明在此函數(shù)中引用的全局變量
舉例：
/**
* Simuliert include_once in PHP 3.
*
* @global array $__used_files 已經(jīng)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
指明包含的文件的信息。
舉例：
/**
* 抽象繪圖類的定義.
*
* @includeFunction: _require_
*/
require("abstract.php");




@link URL description 使用范圍：class, function, var, module, define, use
定義在線連接，如上面3.4中講到的，你可以使用@link添加適當?shù)脑诰�鏈接。
例如：@link http://www.phpdoc.de/ PHPDoc Home

@magic description
這個標記在phpdoc中沒有說明，具體用法現(xiàn)在仍不清楚

@module label 使用范圍：module
定義歸屬的模塊信息，label是模塊的名字，擁有相同的模塊名字的函數(shù)在索引分類中將被組合在一起。如果你沒有使用OOP的思想來編寫PEAR代碼，那么建議你使用這個標記把相關的函數(shù)歸集到相應的模塊下面，這樣你的整體的框架不至于過于零散和混亂。

@modulegroup label 使用范圍：module
定義歸屬的模塊組 label是這個模塊組的名字，如果你的應用程序的模塊很多，你可以把不同的模塊按照邏輯功能的不同，劃分成相應的模塊組，這樣，你的應用框架可以有比較清晰的邏輯關系。這是對于沒有使用OOP編程的來說的，如果使用OOP的思想，沒有必要使用模塊組的概念，因為直接使用"包-超類--基類--子類"的形式來體現(xiàn)你的框架結構要比使用"包-模塊組-模塊"的形式好的多。

@package label 使用范圍：class, module
定義歸屬的包的信息,label 是這個包的名字。相同的包的名字的類在最終文檔索引中將被分在一起。實際上，包還可以理解為不同的名字空間，雖然PHP沒有名字空間的概念，但是你可以把相關的類、模塊都歸屬于同一個包，這樣，相當于組織了一個名字空間，當然，你的應用框架可能會有不同的包，可惜的是，這種情況下從語法上是得不到名字空間這種保證的，你只能通過人為地去避免不同的包的函數(shù)或者類重名。

@param[eter] (object objecttype type) [$varname] [description] 使用范圍：function
定義函數(shù)或者方法的參數(shù)信息。這是最常使用的文檔標記了。

ojecttype 是對象的類名，type 指出這個參數(shù)的類型，它可以是下列類型：

string 該參數(shù)是一個字符型變量。
array 該參數(shù)是一個數(shù)組。
integer 該參數(shù)是一個數(shù)值型。
integer (octal) 該參數(shù)是一個數(shù)值型，并且是按照八進制方式存放。
integer (hexadecimal) 該參數(shù)是一個數(shù)值型，并且是按照十六進制方式存放。
boolean 該參數(shù)是一個布爾型。
mixed 該參數(shù)的類型是可變的，可以上面幾種類型的組合。不過，在隨后的說明中一般要說明可以接受的變量的類型。
$varname 是形參的名稱
[description] 是對于參數(shù)的說明。
如果函數(shù)接受的是多個參數(shù)，那么要按照從左到右，依次用@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
定義函數(shù)或者方法的返回信息。
返回信息的類型同@param一樣，$varname是返回變量的名稱，可有可無。不同的是@return只有一個，不會出現(xiàn)多個@return

@see (function() $varname ((module class)::)(function() $varname)) [, ...] 使用范圍：class, function, var, module, define, use
定義需要參考的函數(shù)、變量，并加入相應的超級連接。這也是較常用的標記。對于相關的函數(shù)，變量，你可以使用@see來增加一個到相關函數(shù)和變量的鏈接。多個相關的函數(shù)、變量寫在一行，中間用逗號來分隔。
參考的函數(shù)、變量如果是當前類或模塊的，那么你可以直接寫函數(shù)、或者變量的名，如果是函數(shù)那么要在函數(shù)名后面加上括號（），變量名要加上$。需要注意的，這里所謂的變量名也應該是你用@var來說明過的，否則，phpdoc將無法找到相關的參照而報錯。
如果你想引用其他類或者其他模塊的函數(shù)或者是變量，那么，你可以在函數(shù)名、變量名前面加上類或模塊的名字作為范圍指示，中間用：：來分隔。

下面是一些例子：
@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函數(shù)或者方法是從哪個版本開始引入的。

@static 使用范圍：class, function, var
指明變量、類、函數(shù)是靜態(tài)的。

@throws exception [, exception] 使用范圍： function
指明此函數(shù)可能拋出的錯誤異常,極其發(fā)生的情況
如果你預料到在這個函數(shù)中有產生異常的條件，那么你可以使用@throws標記來說明這些異常是什么，什么情況下產生異常。比如，讀取磁盤文件出錯，無法連接數(shù)據(jù)庫，網(wǎng)絡連接超時或者是在一些情況下，你"故意"拋出的異常等等。

@todo 使用范圍：class, function, module, use
指明應該改進或沒有實現(xiàn)的地方

@var[iable] (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: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp

5. 生成文檔
5.1 安裝PHPDOC
安裝PHPDOC很簡單,實際上因為它已經(jīng)隨同PHP 4.05一同發(fā)布了,所以如果你的PHP是4.05,那么在PEAR目錄下面會發(fā)現(xiàn)PHPDOC這個模塊.如果你沒有發(fā)現(xiàn),你可以從PHPDOC的CVS獲得一份最新的源碼.

5.2 運行PHPDOC
運行PHPDOC需要做一些準備工作,首先要調整你的PHP.INI的參數(shù)，

因為PHPDOC運行的時間比一般的PHP應用要長，很可能會超過你在PHP.INI中定義的最大運行時間（缺省是30秒），根據(jù)作者的建議：PIII，60秒，120秒PII，240秒MMX200，480秒如果配置更低的話。如果出現(xiàn)超時，你可以自己適當延長這些數(shù)值。

在php.ini中修改：
;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 480
memory_limit = 8388608




如果你不愿意或者沒有修改php.ini的權限，那么你可以使用set_time_limit（）函數(shù)來設置這個時間，使用方法： set_time_limit(480); 設置從此點開始，運行480秒后才超時。將這個函數(shù)加在index.php中，就可以和修改php.ini達到同樣的效果。

其次，你要修改phpdoc目錄下面的index.php文件：
// Directory with include files
define("PHPDOC_INCLUDE_DIR", "c:/www/apache/doc/");


將"c:/www/apache/doc/修改成你的phpdoc的目錄
// Important: set this to the Linebreak sign of your system!
define("LINEBREAK", "\r\n");
這是定義換行的標志，DOS下面是換行+回車，UNIX下面只是回車就可以。

下面，為你的要生成文檔的應用程序做一些定制工作：
// Sets the name of your application.
// The name of the application is used e.g. as a page title
$doc->setApplication("PHPDoc");

setApplication（）用來設置你的應用程序的名稱，將PHPDOC替換成你應用程序的名字。

// directory where your source files reside:
$doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);

setSourceDirectory（）設置你的應用程序的PHP源文件所在的目錄，將PHPDOC_INCLUDE_DIR替換成你實際的目錄。

// save the generated docs here:
$doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");

setTarget（）設置你的API文檔存放的目錄，PHPDOC將在這個目錄下面生成XML及HTML文件。將PHPDOC_INCLUDE_DIR."apidoc/"替換成你自己的目錄。

// use these templates:
$doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");

setTemplateDirectory（）設置HTML所使用的模板的目錄。如果你需要使用定制的模板，可以使用這個函數(shù)設置你自己的模板文件所在的目錄。

// source files have one of these suffixes:
$doc->setSourceFileSuffix( array ("php", "inc") );

setSourceFileSuffix（）用來設置需要分析的PHP源文件的擴展名，如果你使用了別的擴展名，需要在這里添加，比如如果你有以前的php3文件，需要添加：
$doc->setSourceFileSuffix( array ("php", "inc"，"php3") );


這樣，基本的定制工作就完成了，現(xiàn)在你可以在瀏覽器中運行index.php,出現(xiàn)了歡迎信息后,就是開始分析文檔了.根據(jù)機器的狀況和所分析的源代碼文件的數(shù)量不同,文檔分析過程所需的時間也不會相同.文檔分析結束后,瀏覽器會顯示FINISH的字樣,表明分析完成,你可以在剛才指定的目錄下面找到分析結果,包括HTML和XML文件.

5.3 實用工具
通過PHPDOC的INDEX.PHP雖然可以產生文檔,但是畢竟不是那么方便,這里我給出了一個自己寫的shell程序 makeapidoc ,你可以用它來方便的產生你的API文檔,無須每次都要修改，也不用非要啟動瀏覽器來執(zhí)行。

用法如下:makeapidoc -t 你的應用程序的標題 -s 源程序目錄 -d 生成文檔存放目錄

在使用之前，先修改下面2行：
PHPDOC_DIR="/usr/local/lib/php/pear/PHPDoc" # windows: c:/php/pear/PHPDoc
PHPBIN="/usr/local/bin/php" #windows: c:/php/php.exe
PHPDOC_DIR是PHPDOC的目錄，PHPBIN是PHP可執(zhí)行文件的路徑。


這個程序實際上是把PHP作為一個SHELLSCRIPT來使用了，不過是嵌在BASH中使用，實際上PHP完全可以做為普通的SHELL腳本一樣運行，只需加上 -q 參數(shù)，這樣就不打印HTTP HEADER了。


6. 進階：定制輸出的文檔
如果你認為缺省的PHPDOC產生的HTML文檔不夠美觀,你想做進一步的改進,比如你想把一些注釋換成中文或者是其他的文字,你想加入你的LOGO,或者是你的聯(lián)系方式,換成一個漂亮的背景圖案,有沒有方法可以作到?答案是當然可以,并且非常簡單.

PHPDOC在輸出HTML格式的API文檔的時候,使用的是PEAR的IT,ITX模塊,這是類似PHPLIB的TEMPLETE.CLASS的PEAR模塊,因此,你可以方便地定制和修改缺省的模板來為你所用.

我們先看看PHPDOC/renderer/html/templates: class.html classtree.html elementlist.html frame_packageelementlist.html
frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html xmlfiles.html

你會看到上面的這些文件,沒錯,這些就是PHPDOC用來產生API HTML的模板,現(xiàn)在你可以用你的編輯器來修改這些模板了,這里給出基本的修改原則:

對于用{}圈起來的標記,這些是一些變量的標記,在運行時刻,PHPDOC將會用實際的變量值替換到相應的位置.因此,你務必要保留全部的變量標記,否則運行時將會出錯.
你要注意<!--Begin Xxx-loop --><!--End Xxx -loop-->之類帶LOOP的注釋,在這2個標記中間的部分,將會用于循環(huán)輸出,所以,你在設計模板時要考慮到循環(huán)使用,是否會破壞你頁面的美觀,最簡單的比如:如果循環(huán)的部分是在一個表格內,你要用<tr>用來分隔各循環(huán)調用的部分,同時應該保證各個<TD></TD>是匹配關閉的.
當你修改的地方不大,你也可以直接修改樣式表phpdoc.css的內容,這樣也可以達到你要求的效果
你可以把模板存放在不同的目錄，通過setTemplateDirectory（）設置不同的模板路徑，就可以生成不同格式的API文檔

7. 參考資源

PHPDOC HOME
PHPDOC CVS