前言：
使用phpDocumentor的好处：
你喜歡寫文件嗎？我不喜歡。尤其是在趕工的時候，哪來的美國時間寫文件；就算有時間也是希望趕快把事情做完閃人，怎樣都輪不到寫文件的時候。
文件需要嗎？雖然不喜歡寫文件，但文件真的是必要的。對自己而言，正當在趕案子兵荒馬亂的時候，突然要某個以前寫過的函式結果不知道放哪去了，這時心情會很糟很糟的去把以前的碼挖出來一份一份看，才能找出所要的函式，這樣更浪費時間。對於他人而言，要是每個人寫出來的東西都可以再讓其它人了解，並且進一步使用其它人早已寫好的元件，可以讓我們再省下時間來多喝幾杯咖啡。
那要怎麼樣讓編寫文件輕鬆又自在？ phpDocumentor 就是一個現成好用的工具，只要在寫程式時順手寫上一點點的註解，困難一點的可以再加上一點點的範例。寫完後交給 phpDocumentor 編譯，一下子圖文並茂的程式文件自動就產生了。而且它還不只可以產生 HTML 檔，還可以產生出 PDF, CHM 等文件。就算產生 HTML 檔，還有許多的風格可以選擇。這樣好用的工具放著不用，實在太可惜了。
這份資料裡，只會出現馬上能用的資料，除了這個簡介外，不會廢話太多，所以文件中的文句也冰冷了些。會這樣做的目的是希望文件的每一個部份都能讓讀者快速吸收，任何一個例子複製下來後馬上能用。文件中的每個樣版我都是精心設計過，起碼我以後要用的時候不必再想說要寫一個類別正常需要哪些 Tag ，只要把樣版複製下來以後就直接可以用了。
由於此文件中資料只有使用上最需要的部份（也是一定能用的部份），因此若在使用上想要了解更多，可以到 phpDocumentor 的官方網站 (http://www.phpdoc.org/)上找到所需資料。
——————摘自 《phpDocumentor筆記 0 立即體驗》
http://pkwbim-programming-note.blogspot.com/2008/01/phpdocumentor-0.html#0.4
其实这篇文章已经写的比较简要，但是为了防止哪天这个网站被盾了，我还是抄到自己的blog比较安全。
简而言之，phpDocumentor就适合我这样写过代码就忘了的人，规范的书写注释还能生成文档，多省事。
1.安装
1.1如果没有安装过pear，可以先运行PHP目录下的go-pear.bat安装。
1.2安装过pear之后，使用下面的命令安装phpDocumentor：
\php5\PEAR\pear install -o PhpDocumentor
2.字符编码的问题
看到很多人都说需要改字符编码，但是我下载的phpDocumentor v1.4.2 没有遇到这个问题，也没有
查找到”iso-8859-1″这个字符串。
3.生成文件
步驟
3.1 将範例碼存成 example.php 置於 \project\php_project\下。
3.2 在命令列下用以下指令
phpdoc –parseprivate -o HTML:frames:earthli -f \project\php_project\example.php -t \project\php_project\docs
或
phpdoc –parseprivate -o HTML:Smarty:PHP -d \project\php_project\ -t \project\php_project\docs
3.3 解說
* –parseprivate： 是將私有 (private) 成員函式或私有變數等等也都加入程式文件裡。沒有這參數的話，產生出的文件裡只會有公開的 (public) 和受保護的 (protected) 的成員函式和變數。
* -f ： 是指針對某個檔案產生註解文件。
* -d ： 針對某個目錄（含其子目錄）產生註解文件。
* -t ： 指定要輸出的目錄
* -o ： 指定輸出格式，上例的格式有兩種
o HTML:frames:earthli ： 是輸出有一種帶有框架 (frame) 的說明文件，所產生出來的文件非常漂亮。Zend Framework 的 API 文件就是採用這種風格。
o HTML:Smarty:PHP ： 產生的文件看起來就像是 PHP 網站上或是 phpDocumentor 官網上的的一樣。
待程式結束後，瀏覽剛剛指定產生文件的目錄下，會有一個 index.html 檔，以瀏覽器打開它就可以看到 phpDocumentor 產生出來的程式文件。倘若在產生文件的過程中，有任何的錯誤，這些錯誤會出現在 error.html檔裡。
4.范例
<?php /** * phpDocumentor 使用示範 * 這個檔案是一個簡單的示範 * 內容涵蓋了許多常用的註解方式。 * 有任何的問題請和作者連絡 * @package phpDocumentorExample * @author 多采多姿 <pkwbim.programming@gmail.com> * @version 0.1b */ /** * 這是 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 * 2. ordered item 2 * 清單在此結束 * * @package phpDocumentorExample * @author 多采多姿 * @since 1.0rc1 * @version 0.2b * */ class MyClass { /** * 這裡是成員變數的註解 * * @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) { } } ?>
要注意所有的注释都是有两个星号的C-style注释，如下所示
/**
*
*/