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

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

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

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

在第一篇pear的編碼規(guī)則中有一條，pear程序中的注釋?xiě)?yīng)該能夠被phpdoc轉(zhuǎn)換。由此可見(jiàn)，phpdoc在pear中的作用可不小。今天，我們將詳細(xì)討論phpdoc，這個(gè)優(yōu)秀的pear程序。

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

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

2. phpdoc的結(jié)構(gòu)及功能
由于phpdoc本身也是符合pear的應(yīng)用程序，我們首先了解一下它的結(jié)構(gòu)。phpdoc是全部采用OOP的思想來(lái)編寫(xiě)的，這也是PEAR所推薦的方式,phpdoc的工作原理：

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

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

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

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

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

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

3.1 文檔注釋
文檔注釋實(shí)際上是一些特殊形式的多行注釋?zhuān)话闶欠旁谀阈枰⑨尩奶囟ǖ年P(guān)鍵字(這些關(guān)鍵字是指將會(huì)被phpdoc分析的那些關(guān)鍵字，相關(guān)的關(guān)鍵字列表請(qǐng)參看后面第4節(jié)的說(shuō)明）前面。下面是一個(gè)文檔注釋的例子：

3.2 非文檔性注釋
如果你的注釋沒(méi)有放在那些phpdoc指定的關(guān)鍵字前面，那么phpdoc認(rèn)為你所作的這些注釋是屬于非文檔注釋?zhuān)瑢⒉粫?huì)被phpdoc所分析，也不會(huì)出現(xiàn)在你產(chǎn)生的api文當(dāng)中。

3.3 如何書(shū)寫(xiě)你的文檔性注釋
從3.1 我們可以看到，一個(gè)文檔性的注釋?zhuān)怯?個(gè)部分組成的，分別是：功能簡(jiǎn)述區(qū)，功能詳細(xì)說(shuō)明區(qū)，文檔標(biāo)記區(qū)。

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

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

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

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

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

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

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

   /**     * 設(shè)置用戶記錄集     *     * @param text  給定的表名     */    function set_user_record($table) {

你從上面這段注釋中能夠知道什么？因此，這段注釋實(shí)際上是廢話，因?yàn)槟銖暮瘮?shù)名稱(chēng)上是可以看出的，下面是改進(jìn)后的：

• 適當(dāng)?shù)厥褂面溄印槟阄臋n中引用的API名稱(chēng)（包括你的其他類(lèi)及方法，PHP的函數(shù)等）添加適當(dāng)?shù)逆溄邮呛苁軞g迎的：你可以使用@link標(biāo)記來(lái)添加到相關(guān)的API的鏈接，不過(guò)，你沒(méi)有必要為文檔中引用的所有的API都添加連接，這樣會(huì)很不美觀，這里有一個(gè)簡(jiǎn)單的標(biāo)準(zhǔn)：如果用戶在這個(gè)地方看到某個(gè)API，確實(shí)希望要去點(diǎn)擊以便獲取更多信息，這樣有助于他們?nèi)ダ斫饽愕奈臋n，并且即使添加了鏈接，只在它第一出現(xiàn)的是時(shí)候添加，沒(méi)有必要重復(fù)添加相同的LINK。
• 由于PHPDOC的功能限制，一個(gè)PHP文件只定義一個(gè)類(lèi)或模塊，不要把類(lèi)和模塊的定義放在同一個(gè)文件里，否則PHPDOC可能無(wú)法工作，至少目前版本是這樣。如果你的框架使用OOP來(lái)構(gòu)建，應(yīng)避免同時(shí)使用模塊或模塊組；同時(shí)應(yīng)該仔細(xì)規(guī)劃你的應(yīng)用結(jié)構(gòu)，你的應(yīng)用框架應(yīng)該是一個(gè)類(lèi)似樹(shù)型的結(jié)構(gòu)，頂層的分支不要太多，例如你可以設(shè)計(jì)2個(gè)超類(lèi)，分別是作為正常應(yīng)用和錯(cuò)誤處理的超類(lèi)，其余的都從這2個(gè)類(lèi)派生出來(lái)。

  4. PHPDoc關(guān)鍵字及文檔標(biāo)志
  4.1 關(guān)鍵字
  class 、function 、var 、include (include_once, require, require_once) 、define

  在以上這些關(guān)鍵字前面所做的注釋?zhuān)急徽J(rèn)為是文檔性注釋。

  4.2 文檔標(biāo)記
  說(shuō)明：使用范圍是指該標(biāo)記可以用來(lái)修飾的關(guān)鍵字，或其他文檔標(biāo)記
  @abstract 使用范圍：class, function, var
  說(shuō)明當(dāng)前類(lèi)是一個(gè)抽象類(lèi)。

  注釋?zhuān)簭腜HP語(yǔ)言角度來(lái)說(shuō)，它并不象JAVA，C++那樣，支持抽象類(lèi)這個(gè)概念。也沒(méi)有相應(yīng)的關(guān)鍵字來(lái)修飾某個(gè)類(lèi)是抽象類(lèi)。由于PHPDOC實(shí)際上大部分是借鑒了JAVADOC的做法，因此很多文檔標(biāo)記也是直接從JAVADOC中沿襲過(guò)來(lái)，如abstract,access,final等等。雖然這些特性沒(méi)有從語(yǔ)言級(jí)別得到支持，不過(guò)從使用者角度來(lái)遵循這些特性，仍是值得推薦的。

  舉例：

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

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

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

  舉例：

  /*** 這是一個(gè)繪五星圖案的抽象類(lèi).* @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地址，其他的通訊信息。如果有多個(gè)作者，按照其先后次序，使用多個(gè)@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

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

  舉例：

  /*** 這是一個(gè)繪五星圖案的抽象類(lèi).* @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
  指明常量
  這個(gè)標(biāo)記實(shí)際上是用來(lái)說(shuō)明php的define關(guān)鍵字定義的常量。

  @copyright description 使用范圍：class, function, var, module, define, use
  指明版權(quán)信息。

  @deprec[ated] label 使用范圍：class, function, var, module, define, use
  指明不推薦或者是廢棄的信息.

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

  例子：

  /*** 過(guò)時(shí)的類(lèi)** @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
  指明當(dāng)前的注釋將不進(jìn)行分析，不出現(xiàn)在文擋中

  @final 使用范圍：class, function, var
  指明這是一個(gè)最終的類(lèi)、方法、屬性，禁止派生、修改。
  舉例：

  /**  * 圓周率    * @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
  指明包含的文件的信息。
  舉例：

  /*** 抽象繪圖類(lèi)的定義.** @includeFunction: _require_*/require("abstract.php");

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

  @magic description
  這個(gè)標(biāo)記在phpdoc中沒(méi)有說(shuō)明，具體用法現(xiàn)在仍不清楚

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

  @modulegroup label 使用范圍：module
  定義歸屬的模塊組 label是這個(gè)模塊組的名字，如果你的應(yīng)用程序的模塊很多，你可以把不同的模塊按照邏輯功能的不同，劃分成相應(yīng)的模塊組，這樣，你的應(yīng)用框架可以有比較清晰的邏輯關(guān)系。這是對(duì)于沒(méi)有使用OOP編程的來(lái)說(shuō)的，如果使用OOP的思想，沒(méi)有必要使用模塊組的概念，因?yàn)橹苯邮褂?包-超類(lèi)--基類(lèi)--子類(lèi)"的形式來(lái)體現(xiàn)你的框架結(jié)構(gòu)要比使用"包-模塊組-模塊"的形式好的多。

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

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

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

  • string 該參數(shù)是一個(gè)字符型變量。
  • array 該參數(shù)是一個(gè)數(shù)組。
  • integer 該參數(shù)是一個(gè)數(shù)值型。
  • integer (octal) 該參數(shù)是一個(gè)數(shù)值型，并且是按照八進(jìn)制方式存放。
  • integer (hexadecimal) 該參數(shù)是一個(gè)數(shù)值型，并且是按照十六進(jìn)制方式存放。
  • boolean 該參數(shù)是一個(gè)布爾型。
  mixed 該參數(shù)的類(lèi)型是可變的，可以上面幾種類(lèi)型的組合。不過(guò)，在隨后的說(shuō)明中一般要說(shuō)明可以接受的變量的類(lèi)型。
  $varname 是形參的名稱(chēng)
  [description] 是對(duì)于參數(shù)的說(shuō)明。
  如果函數(shù)接受的是多個(gè)參數(shù)，那么要按照從左到右，依次用@param對(duì)齊列出，如下面所示：

  *    * @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ù)或者方法的返回信息。
  返回信息的類(lèi)型同@param一樣，$varname是返回變量的名稱(chēng)，可有可無(wú)。不同的是@return只有一個(gè)，不會(huì)出現(xiàn)多個(gè)@return

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

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

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

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

  @todo 使用范圍：class, function, module, use
  指明應(yīng)該改進(jìn)或沒(méi)有實(shí)現(xiàn)的地方

  @var[iable] (object objecttype|type) [$varname] [description] 使用范圍：var
  定義說(shuō)明變量/屬性。
  object objecttype|type 定義你的變量的類(lèi)型，同@param一樣
  $varname 該變量的名字，你可以從其他地方使用@see來(lái)引用這個(gè)名字
  description 對(duì)變量的描述

  @version label 使用范圍：class, function, module, use
  定義版本信息.
  你當(dāng)然可以自己手工寫(xiě)這些版本信息，不過(guò)PEAR推薦你使用CVS的$Id標(biāo)記來(lái)自動(dòng)標(biāo)示你的版本信息。形式如下：

  @version $Id
  這樣，當(dāng)你checkout的時(shí)候，CVS自動(dòng)會(huì)擴(kuò)展成： @version $Id: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp

  5. 生成文檔
  5.1 安裝PHPDOC
  安裝PHPDOC很簡(jiǎn)單,實(shí)際上因?yàn)樗呀?jīng)隨同PHP 4.05一同發(fā)布了,所以如果你的PHP是4.05,那么在PEAR目錄下面會(huì)發(fā)現(xiàn)PHPDOC這個(gè)模塊.如果你沒(méi)有發(fā)現(xiàn),你可以從PHPDOC的CVS獲得一份最新的源碼.

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

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

  在php.ini中修改：

  ;;;;;;;;;;;;;;;;;;;; Resource Limits ;;;;;;;;;;;;;;;;;;;;max_execution_time = 480memory_limit = 8388608

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

  其次，你要修改phpdoc目錄下面的index.php文件：

  // Directory with include filesdefine("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");
  這是定義換行的標(biāo)志，DOS下面是換行+回車(chē)，UNIX下面只是回車(chē)就可以。

  下面，為你的要生成文檔的應(yīng)用程序做一些定制工作：

  // Sets the name of your application.// The name of the application is used e.g. as a page title$doc->setApplication("PHPDoc");setApplication（）用來(lái)設(shè)置你的應(yīng)用程序的名稱(chēng)，將PHPDOC替換成你應(yīng)用程序的名字。// directory where your source files reside:$doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);setSourceDirectory（）設(shè)置你的應(yīng)用程序的PHP源文件所在的目錄， 將PHPDOC_INCLUDE_DIR替換成你實(shí)際的目錄。// save the generated docs here:$doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");setTarget（）設(shè)置你的API文檔存放的目錄，PHPDOC將在這個(gè)目錄下面生成XML及HTML文件。 將PHPDOC_INCLUDE_DIR."apidoc/"替換成你自己的目錄。// use these templates:$doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");setTemplateDirectory（）設(shè)置HTML所使用的模板的目錄。如果你需要使用定制的模板， 可以使用這個(gè)函數(shù)設(shè)置你自己的模板文件所在的目錄。// source files have one of these suffixes:$doc->setSourceFileSuffix( array ("php", "inc") );setSourceFileSuffix（）用來(lái)設(shè)置需要分析的PHP源文件的擴(kuò)展名，如果你使用了別的擴(kuò)展名， 需要在這里添加，比如如果你有以前的php3文件，需要添加：$doc->setSourceFileSuffix( array ("php", "inc"，"php3") );

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

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

  用法如下:makeapidoc -t 你的應(yīng)用程序的標(biāo)題 -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í)行文件的路徑。


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

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

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

  我們先看看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

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

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

  7. 參考資源

  • PHPDOC HOME
  • PHPDOC CVS

  作者簡(jiǎn)介 潘凡(Night Sailer)：北京賽迪數(shù)據(jù)有限公司工程師。主要從事是數(shù)據(jù)的分析和轉(zhuǎn)換，以及相關(guān)的開(kāi)發(fā)工作。擅長(zhǎng)使用VB，PERL，PHP進(jìn)行開(kāi)發(fā)以及Linux的中文化工作。近期興趣是Perl,Php與XML的應(yīng)用，PHP的MVC開(kāi)發(fā)模式，PERL-GTK的使用。您可以通過(guò) E-mail:nightsailer@hotmail.com 跟他聯(lián)系。