(转载)phpDocumentor筆記

phpDocumentor很好的php工具。淡水这里转载的台湾同胞的学习笔记，方便查询。

你喜歡寫文件嗎？我不喜歡。尤其是在趕工的時候，哪來的美國時間寫文件；就算有時間也是希望趕快把事情做完閃人，怎樣都輪不到寫文件的時候。

文件需要嗎？雖然不喜歡寫文件，但文件真的是必要的。對自己而言，正當在趕案子兵荒馬亂的時候，突然要某個以前寫過的函式結果不知道放哪去了，這時心情會很糟很糟的去把以前的碼挖出來一份一份看，才能找出所要的函式，這樣更浪費時間。對於他人而言，要是每個人寫出來的東西都可以再讓其它人了解，並且進一步使用其它人早已寫好的元件，可以讓我們再省下時間來多喝幾杯咖啡。

那要怎麼樣讓編寫文件輕鬆又自在？ phpDocumentor 就是一個現成好用的工具，只要在寫程式時順手寫上一點點的註解，困難一點的可以再加上一點點的範例。寫完後交給 phpDocumentor 編譯，一下子圖文並茂的程式文件自動就產生了。而且它還不只可以產生 HTML 檔，還可以產生出 PDF, CHM 等文件。就算產生 HTML 檔，還有許多的風格可以選擇。這樣好用的工具放著不用，實在太可惜了。

這份資料裡，只會出現馬上能用的資料，除了這個簡介外，不會廢話太多，所以文件中的文句也冰冷了些。會這樣做的目的是希望文件的每一個部份都能讓讀者快速吸收，任何一個例子複製下來後馬上能用。文件中的每個樣版我都是精心設計過，起碼我以後要用的時候不必再想說要寫一個類別正常需要哪些 Tag ，只要把樣版複製下來以後就直接可以用了。

由於此文件中資料只有使用上最需要的部份（也是一定能用的部份），因此若在使用上想要了解更多，可以到 phpDocumentor 的官方網站 (http://www.phpdoc.org/)上找到所需資料。

此文件中所有的測試環境是 Windows XP + PHP 5.2.1 + phpDocumetor v.1.4.1。

假設你的 php 目錄在 php5

步驟安裝 PEAR 基本套件

請先查看 php5PEAR 裡的內容，若裡面是空的則是還沒安裝 PEAR 基本套件，請以命令列模式下執行 PHP 目錄下的 go-pear.bat。

在執行過程中，會要求回答幾個問題，都用預設值即可。

執行完畢後會在 php5PEAR 下裝了 PEAR 基本套件。安裝 phpDocumentor

在 PHP 目錄下執行以下命令：

php5PEARpear install -o PhpDocumentor 此命令會安裝 phpDocumentor 及其相依套件。裝好以後， phpDocumentor 的所有程式會放在 php5PEARPhpDocumentor 裡。

如此就安裝完成。

步驟把 php5PEARPhpDocumentorphpDocumentor 裡的（含子目錄）的文件裡的所有 iso-8859-1 的字串全部換成 utf-8 。這種事情我是交給我的文字編輯器 (PSPad) 來做多檔的取代動作。

/**

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

/**

圓周率
圓周和直徑的比值 */ define(‘pi’, 3.14159);

/**

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

/**

這是MyClass的標題
建立簡寫型的清單
這裡建立一份無序清單
- 項目一
- 項目二，
每個項目可以是多行，
就像這個項目，
這行還在項目二中
- 項目三
清單結束，因為沒縮排
這裡建立一份有序清單
1 有序的項目一，數字後一定要加一個空白。
2 有序的項目二
有序清單的另一種寫法
1. ordered item 1
1. ordered item 2
清單在此結束
@package phpDocumentorExample
@author 多采多姿
@since 1.0rc1
@version 0.2b
這裡是成員變數的註解
@var string 成員變數的註解
@access private */ private $_variable = “Hello”;

/**

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

在命令列下用以下指令 phpdoc –parseprivate -o HTML:frames:earthli -f projectphp_projectexample.php -t projectphp_projectdocs 或 phpdoc –parseprivate -o HTML:Smarty:PHP -d projectphp_project -t projectphp_projectdocs 解說

–parseprivate：是將私有 (private) 成員函式或私有變數等等也都加入程式文件裡。沒有這參數的話，產生出的文件裡只會有公開的 (public) 和受保護的 (protected) 的成員函式和變數。

-f ：是指針對某個檔案產生註解文件。

-d ：針對某個目錄（含其子目錄）產生註解文件。

-t ：指定要輸出的目錄

-o ：指定輸出格式，上例的格式有兩種

HTML:frames:earthli ：是輸出有一種帶有框架 (frame) 的說明文件，所產生出來的文件非常漂亮。Zend Framework 的 API 文件就是採用這種風格。

HTML:Smarty:PHP ：產生的文件看起來就像是 PHP 網站上或是 phpDocumentor 官網上的的一樣。待程式結束後，瀏覽剛剛指定產生文件的目錄下，會有一個 index.html 檔，以瀏覽器打開它就可以看到 phpDocumentor 產生出來的程式文件。倘若在產生文件的過程中，有任何的錯誤，這些錯誤會出現在 error.html檔裡。

转载：http://pkwbim-programming-note.blogspot.com/2008/01/phpdocumentor-0.html

淡水备注：生成文案也可以用phpDesigner2008来做的。

樣版基本樣式如下： /**

這是文件區塊 (DocBlock) 的標題
第二行開始就是描述
描述可以延伸好幾行 / 解說文件區塊的開頭一定要有兩個星號（/**），接下來的每一行的開頭要有一個，結束時使用*/為結尾。不符合文件區塊格式的註解 phpDocumentor 不會進行處理。標題只能一行。（官方手冊上是說三行，真莫名其妙）。標題下一行直接可接描述。（官方手冊上寫一定要空一行，經實驗這是不必要的）描述是寫詳細解釋的地方，除了可以寫一般的文字外，可以用標籤和 Tag 為文件區塊增加功能。（標籤和 Tag 之後會解釋）描述可省略。要為任何一段程式做文件註解，最簡單的方式就是在要解釋的程式之前放一個 DocBlock 。如下所示： /**
這函數叫foo，可能沒有什麼用
要為一個函數做文件註解，
只要在函式之前放一個文件區塊即可 / function foo() { … } 文件區塊預設是為它接下來的程式區塊做註解，否則會造成誤判。如： /*
這個不是 foo 的文件區塊
它是 define 的文件區塊 */ define(‘DEBUG’, 0); function foo(DEBUG) { … } 並不是將 DocBlock 放在任何想要解釋的程式前，它的內容就會出現在 phpDocumentor 所產生的註解文件內。會產生在註解文件內的文件區塊有以下幾類：

<li>引入檔的文件區塊 </li>

<li>類別的文件區塊 </li>

<li>函式的文件區塊 </li>

<li>常數的文件區塊</li>

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

樣版 /**

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

<li>@author 用來標明這檔案的作者，在作者名字之後可以再接電郵位置，但電郵位置一定要放在 < 和 > 之間。

電郵位置可省略。

<li>@version 用來標明這份檔案的版本。 </li>

<li>@version 和 @author不是檔案層級文件區塊內必要的 Tag，但是一般都會提供這兩樣的資訊。</li>

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前的文件區塊不會出現在註解文件裡。

樣版 /**

這是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 為函式寫註解。

樣版 /**

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

樣版 /**

建立簡寫型的清單
這裡建立一份無序清單
- 項目一
- 項目二，
每個項目可以是多行，
就像這個項目，
這行還在項目二中
- 項目三
清單結束，因為沒縮排
這裡建立一份有序清單
1 有序的項目一，數字後一定要加一個空白。
2 有序的項目二
有序清單的另一種寫法
1. ordered item 1
1. ordered item 2
清單在此結束 */ 解說以- 開頭就可以建立一個無序清單的項目，減號後面一定要接一個空白。以數字加上點號（例：1. ）或是只有數字（例：1 ），就可以建立有序清單，兩種方式後面都需要加上一個空白。多行的項目要縮排若要結束清單，則不縮排直接填內容即可。

最后修改于 2008-11-20