phpDocumentor筆記 - 1 馬上能用的基礎

phpDocumentor筆記

這篇原本是我研究 phpDocumentor 的筆記，怎知愈寫愈多，到了後來都變成了一篇教學文件。變成了教程也不錯，這樣之後學的人也輕鬆多了，因為在我研究 phpDocumentor 的過程中，還發現了一些地方 phpDocumentor 的實作和手冊上寫的不太一樣，所以我了花了些時間把官方手冊上的例子一一測過，以下的例子都是在 phpDocumentor v.1.4.1 下可以使用的。若還有錯誤，請通知我。

 

1 馬上能用的基礎

1.1. DocBlock

top
在 phpDocumentor 中，每一個註解單位稱為 Documentation block ，簡稱 DocBlock，在此文件裡我稱它為文件區塊。

樣版

基本樣式如下：

/**
* 這是文件區塊 (DocBlock) 的標題
* 第二行開始就是描述
* 描述可以延伸好幾行
*/

解說

• 文件區塊的開頭一定要有兩個星號（/**），接下來的每一行的開頭要有一個*，結束時使用*/為結尾。
• 不符合文件區塊格式的註解 phpDocumentor 不會進行處理。
• 標題只能一行。（官方手冊上是說三行，真莫名其妙）。
• 標題下一行直接可接描述。（官方手冊上寫一定要空一行，經實驗這是不必要的）
• 描述是寫詳細解釋的地方，除了可以寫一般的文字外，可以用標籤和 Tag 為文件區塊增加功能。（標籤和 Tag 之後會解釋）
• 描述可省略。
• 要為任何一段程式做文件註解，最簡單的方式就是在要解釋的程式之前放一個 DocBlock 。如下所示：

  /**
  * 這函數叫foo，可能沒有什麼用
  *
  * 要為一個函數做文件註解，
  * 只要在函式之前放一個文件區塊即可
  */
  function foo() {
  ...
  }
  

• 文件區塊預設是為它接下來的程式區塊做註解，否則會造成誤判。如：

  /**
  * 這個不是 foo 的文件區塊
  *
  * 它是 define 的文件區塊
  */
  define('DEBUG', 0);
  function foo(DEBUG) {
  ...
  }
  

• 並不是將 DocBlock 放在任何想要解釋的程式前，它的內容就會出現在 phpDocumentor 所產生的註解文件內。會產生在註解文件內的文件區塊有以下幾類：
  1. 檔案層級的文件區塊
  2. 引入檔的文件區塊
  3. 類別的文件區塊
  4. 函式的文件區塊
  5. 常數的文件區塊

請注意：若急著使用 phpDocumentor ，那麼不必往下讀，因為讀到這裡已足夠讓 phpDocumentor 產生出程式註解文件來。

1.2 為檔案寫註解

top
每一個檔案的第一個 DocBlock 稱為檔案層級文件區塊 (file-level DocBlock) ，是保留來為檔案寫註解。它一定會有 @package 指出這個檔案是屬於哪個 package 。

樣版

/**
* 這是一個檔案層級文件區塊 (file-level DocBlock)
*
* 這個文件區塊一定要是整份文件的第一個區塊才能夠成為檔案層級文件區塊
* 一定要有 @package 這個 Tag
* @package PackageName
* @author 多采多姿 
* @version 1.0
*/

解說

• @package 指出此檔是屬於哪個 package ， package 的名字和程式沒有關係，可以自由指定。指定它的用途只是方便管理檔案，讓相關的檔案在產生的註解文件中可以放一起呈現。
• 若在其它的文件區塊內沒有另行宣告所屬的 package ，檔案內的所有常數、函式、類別等等，預設會屬於此檔案層級文件區塊內宣告的 package 。
• 只有在檔案層級的文件區塊和類別所屬的文件區塊裡， @package 才有用。
• 若一個檔案沒有所屬的 package 時，在產生程式文件時會出現沒有指明 package 的警告訊息。
• @author 用來標明這檔案的作者，在作者名字之後可以再接電郵位置，但電郵位置一定要放在 < 和 > 之間。
• 電郵位置可省略。
• @version 用來標明這份檔案的版本。
• @version 和 @author不是檔案層級文件區塊內必要的 Tag，但是一般都會提供這兩樣的資訊。

1.3 為常數及變數寫註解

top
PHP 裡變數可大致可分為以下幾類：全域變數、函數參數、函數內變數、類別的靜態成員變數、類別物件的成員變數。這部份只討論全域變數，函數參數的註解方式請參考 1.4 為函式寫註解。

樣版

/**
* 圓周率
* 圓周和直徑的比值
*/
define('PI', 3.14159);

/**
*  這是 funtion1 的註解區塊標題
*  這是 funtion1 的描述
*  @global int 這是函式內第一個全域變數的註解，就是 $global1 的註解
*  @global string 這是函式內第二個全域變數的註解，就是 $global2 的註解
*  @param bool $arg1 這是函式參數 $arg1 的註解
*  @param intstring $arg2 這裡是函式參數 $arg2 的註解
*  @return mixed 傳回值的註解
*/
function function1($arg1, $arg2) {
global $global1, $global2;
/**
* 這註解是不會出現在註解文件裡。
*/
$arg = 3;
  return array($arg1, $arg2);
}

解釋

• 在對常數寫註解，只要在常數前放一個註解文件即可。省略也無妨， phpDocumentor 還是會自動把所有的常數找出來，在註解文件裡整理成表。
• 在要函式內使用全域變數時，在函式前的文件區塊內使用 @global 即可為全域變數編寫註解。
• 在@global在使用時不用指明變數名稱，它是依照全域變數在函式內宣告的順序進行註解的判斷。
• global $arg1, $arg2;不能拆成兩行寫，也就是說寫成下面的樣子， phpDocumentor 的判斷會出很大的問題。

  global $arg1;
  global $arg2;
  

• phpDocumentor 並沒有對於函數內變數特別設計 Tag 來做註解。
• $arg3前的文件區塊不會出現在註解文件裡。

1.4 為函式寫註解

top

樣版

/**
* 函式註解格式樣版
*
* fn 是一個function
* @param intstring $arg1 這裡開始寫參數的註解
* @param mixed $arg2 這裡開始寫參數的註解
* @return mixed 這裡可以寫回傳值的註解
*/
function fn($arg1, $arg2) {
  ...
  return $result;
}

解說

• @param 用來指出函式參數的型態、變數名和描述。
• @return 用來指出函式傳回值的型態和描述。
• 在描述型態時只能用 PHP 認得的型態，如 int, string, array 等等。
• 若參數的型態可能有許多種，那就用 mixed 表示。
• 若型態可能為 int 或 string，那就用 連接兩種型態，但請注意 intstring 中間沒有任何空白。
• @param 和 @return 中的註解可以省略。

1.5 為類別寫註解

top

樣版

/**
* 這是class1
*
* @package PackageName
* @author Cowboy 
* @since 1.0rc1
* @version 1.9b
*/
class Class1 {
/**
* 這裡是成員變數的註解
*
* @var string 成員變數的註解
* @access private
*/
private $_variable = "Hello";

/**
* 這是一個公開的成員函式
*
* @param bool $var1 參數1
* @param stringarray $var2 參數1
* @return void
* @access public
*/
public function set_vars($var1, $var2) {
...
}
}

解說

• Class 1 前的文件區塊裡的 Tag 並不是必要的，但通常會有這幾樣資訊。
• 雖然檔案層級的文件區塊裡有宣告此檔裡的所有程式是屬於哪個 package ，在類別的文件區塊仍然可以再指定。
• @since 指出這類別是從哪個版本以後才加入這個 package 的。
• @access 可以用來指定成員的可視程度 (visibility) 。
• 成員函式的文件區塊部份請參考1.4 為函式寫註解。

1.6 為引入檔案寫註解

top
只要在include_once或require_once前放一個文件區塊即可。

樣版

/**
* 這是 lib.inc.php 的標題
* 這是 lib.inc.php 的描述
*/
include_once('lib.inc.php');

1.7 DocBlock在長描述裡建立簡寫型的清單

top
在DocBlock的長描述裡，我們可以加上- 號建立無序清單，或是以數字1 或1. 建立有序清單。

樣版

/**
* 建立簡寫型的清單
*
* 這裡建立一份無序清單
* - 項目一
* - 項目二，
*   每個項目可以是多行，
*   就像這個項目，
*   這行還在項目二中
* - 項目三
* 清單結束，因為沒縮排
* 這裡建立一份有序清單
* 1 有序的項目一，數字後一定要加一個空白。
* 2 有序的項目二
* 有序清單的另一種寫法
* 1. ordered item 1
* 2. ordered item 2
* 清單在此結束
*/

解說

• 以- 開頭就可以建立一個無序清單的項目，減號後面一定要接一個空白。
• 以數字加上點號（例：1. ）或是只有數字（例：1 ），就可以建立有序清單，兩種方式後面都需要加上一個空白。
• 多行的項目要縮排
• 若要結束清單，則不縮排直接填內容即可。