phpDocumentor筆記 0 立即體驗
0 立即體驗
這篇原本是我研究 phpDocumentor 的筆記，怎知愈寫愈多，到了後來都變成了一篇教學文件。變成了教程也不錯，這樣之後學的人也輕鬆多了，因為在我研究 phpDocumentor 的過程中，還發現了一些地方 phpDocumentor 的實作和手冊上寫的不太一樣，所以我了花了些時間把官方手冊上的例子一一測過，以下的例子都是在 phpDocumentor v.1.4.1 和 PHP 5.2.1 下可以使用的。
0.1 簡介
top
若您已經了解什麼是 phpDocumentor ，可以自行跳過。
你喜歡寫文件嗎？我不喜歡。尤其是在趕工的時候，哪來的美國時間寫文件；就算有時間也是希望趕快把事情做完閃人，怎樣都輪不到寫文件的時候。文件需要嗎？雖然不喜歡寫文件，但文件真的是必要的。對自己而言，正當在趕案子兵荒馬亂的時候，突然要某個以前寫過的函式結果不知道放哪去了，這時心情會很糟很糟的去把以前的碼挖出來一份一份看，才能找出所要的函式，這樣更浪費時間。對於他人而言，要是每個人寫出來的東西都可以再讓其它人了解，並且進一步使用其它人早已寫好的元件，可以讓我們再省下時間來多喝幾杯咖啡。
那要怎麼樣讓編寫文件輕鬆又自在？ phpDocumentor 就是一個現成好用的工具，只要在寫程式時順手寫上一點點的註解，困難一點的可以再加上一點點的範例。寫完後交給 phpDocumentor 編譯，一下子圖文並茂的程式文件自動就產生了。而且它還不只可以產生 HTML 檔，還可以產生出 PDF, CHM 等文件。就算產生 HTML 檔，還有許多的風格可以選擇。這樣好用的工具放著不用，實在太可惜了。
這份資料裡，只會出現馬上能用的資料，除了這個簡介外，不會廢話太多，所以文件中的文句也冰冷了些。會這樣做的目的是希望文件的每一個部份都能讓讀者快速吸收，任何一個例子複製下來後馬上能用。文件中的每個樣版我都是精心設計過，起碼我以後要用的時候不必再想說要寫一個類別正常需要哪些 Tag ，只要把樣版複製下來以後就直接可以用了。
由於此文件中資料只有使用上最需要的部份（也是一定能用的部份），因此若在使用上想要了解更多，可以到 phpDocumentor 的官方網站 (http://www.phpdoc.org/)上找到所需資料。
此文件中所有的測試環境是 Windows XP + PHP 5.2.1 + phpDocumetor v.1.4.1。
0.2 安裝
topphpDocumentor 可以用 PEAR 安裝，在這裡也只介紹這種方式。以下是 Windows 版的安裝步驟：
假設你的 php 目錄在 \php5
步驟
- 安裝 PEAR 基本套件
- 請先查看 \php5\PEAR 裡的內容，若裡面是空的則是還沒安裝 PEAR 基本套件，請以命令列模式下執行 PHP 目錄下的 go-pear.bat。
- 在執行過程中，會要求回答幾個問題，都用預設值即可。
- 執行完畢後會在 \php5\PEAR 下裝了 PEAR 基本套件。
- 安裝 phpDocumentor在 PHP 目錄下執行以下命令：
\php5\PEAR\pear install -o PhpDocumentor
此命令會安裝 phpDocumentor 及其相依套件。裝好以後， phpDocumentor 的所有程式會放在 \php5\PEAR\PhpDocumentor 裡。
0.3 改字碼
topPEAR 有規定，所有的 PEAR 裡的 php 程式都是 iso-8859-1 文件（就是 Latin-1 或「西歐語言」），因此利用 phpDocumentor 產生出的文件，編碼也是預設為 iso-8859-1 。這對使用中文的我們來說很不方便。如果你是和我一樣，不喜歡濫用英文也不喜歡過度強調英文的話，那麼就有需要改變 phpDocumentor 裡的字碼成為 utf-8 使得之後的文件編碼符合我們的需要。
步驟
把 \php5\PEAR\PhpDocumentor\phpDocumentor 裡的（含子目錄）的文件裡的所有 iso-8859-1 的字串全部換成 utf-8 。這種事情我是交給我的文字編輯器 (PSPad) 來做多檔的取代動作。0.4 一個簡單的範例
top範例
<?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) {
}
}
?>
0.5 產生文件
top步驟
- 將 phpDocumentor 0.4 範例碼存成 example.php 置於 \project\php_project\下。
- 在命令列下用以下指令
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
- 解說
--parseprivate： 是將私有 (private) 成員函式或私有變數等等也都加入程式文件裡。沒有這參數的話，產生出的文件裡只會有公開的 (public) 和受保護的 (protected) 的成員函式和變數。-f： 是指針對某個檔案產生註解文件。-d： 針對某個目錄（含其子目錄）產生註解文件。-t： 指定要輸出的目錄-o： 指定輸出格式，上例的格式有兩種HTML:frames:earthli： 是輸出有一種帶有框架 (frame) 的說明文件，所產生出來的文件非常漂亮。Zend Framework 的 API 文件就是採用這種風格。HTML:Smarty:PHP： 產生的文件看起來就像是 PHP 網站上或是 phpDocumentor 官網上的的一樣。
1 則留言:
非常謝謝您的分享，昨天照著做，在目錄
\php5\PEAR\PhpDocumentor\phpDocumentor
找了半天，就是沒發現含有 iso-8859-1 字串的檔案。後來改從上一層目錄開始一個個慢慢找，總算在
\php5\PEAR\data\PhpDocumentor\phpDocumentor
這個目錄之下的一些 tpl 檔案之中，找到含有 iso-8859-1 字串的檔案。經全部置換成 utf-8 後，果然產製出的文件，都可以正常顯示中文。
我想這或許與我的環境是 PHP 5.3.1 + phpDocumentor v.1.4.3 有關。
張貼留言