寫文件是一個程式設計師最最痛苦的事情之一，尤其是寫了一堆程式後有人要你把 Function ，Class 等等等等，寫成一份文件。
這事情不管你是寫 c/c++ , perl , ruby , php 都不例外。
phpDocumentor 是我們的救星! 只要在寫程式的時候，乖乖的寫一點註解，寫一點範例，多一點說明，注意一下格式，等到程式完工後，只要一個指令，就可以立刻把全部程式的說明文件產生出來，而且還有多種樣式可以選擇，甚至可以作成 PDF , CHM 喔…
好了，屁話不多說，先來說說怎麼裝上這好用的東西吧…
phpDocumentor 本身已經是 pear 的成員之一，所以安裝的時候只要用 pear 來安裝即可（以下範例為在 Windows 下進行，以後再補上 LInux 下的）
–如果你已經有裝 php 跟 pear 請跳過–
首先假設我把我的的 php 安裝路徑在 d:\php\
也就是說我從 www.php.net 下載了最新的 php win32 安裝檔案，解開後放在 d:\php\
那麼這個目錄下面應該有 d:\php\PEAR這個目錄，但是當你進去看的時候，你會發現好像沒有 PEAR 相關程式庫阿…
沒錯，這個時候你還沒有安裝 PEAR 請先用 go-pear.php 安裝基本 pear 環境。
那麼在 d:\php 目錄下有一個檔案，叫做 go-pear.bat 請開一個 cmd 視窗去執行他，中間會有一些問題，基本上都照預設值去跑就可以了…
跑玩後，你的 pear 應該會被安裝在 d:\php\PEAR\pear 下面，而幫助你安裝其他 pear 套件的 pear.bat 則在 d:\php\PEAR下面
–安使安裝 phpDocumentor –
安裝 phpDocumentor 的過程也很簡單，只要利用 pear.bat 即可！
使用指令如下
d:\php\PEAR\pear.bat install -o PhpDocumentor
當中有多下一個 -o 的參數，意思是要 pear 把相依的套件也一起下載安裝。
安裝完成後 d:\php\PEAR 下面應該會多一個 phpdoc.bat 的批次檔，我們就可以用這個批次檔來產生我們的文件。
– 使用 phpdoc.bat 產生文件 –
產生文件的方式我通常只有用下面一行指令解決：
d:\php\PEAR\phpdoc.bat -o HTML:Smarty:PHP -d d:\myProject\php_source\ -t d:\myProject\docs
這樣子的意思是說，採用 HTML:Smarty:PHP 的樣板格式，然後原始碼目錄在 d:\myProject\php_source\ ，接著把產生的文件放在 d:\myProject\docs 底下。
當中若是你只要對一個檔案作文件的話，可以把 -d 改成 -f 然後後面接的著就是指定的檔名。
樣板的格式基本上有 HTML, XML, PDF, CHM 四大類別，通常我用的都是 HTML:Smarty:PHP 這個，因為他比較好看!
另外還有就是 CHM:default:default 這個.用來產生 chm 的，不過他產生出來的是 .hhp 檔案，也就是還沒有經過 HTML helper 編譯過的檔案，所以要另外安裝 HTML Helper 來編譯 hhp 檔案就可以產生你要的檔案。
– 最後來說一下怎麼寫註解 –
phpDocumentor 的註解有一定的規格，但是都跟我們原來寫註解的方式很像，只是要注意一下東西而已。
簡單的來看個範例好了
<?php
/**
* 這裡是這個物件的說明
* 可以多行喔!~
*
*/
class MyClass {
/**
* 這裡是變數的說明
*
* @var int
*/
var $a ;
/**
* 這裡是變數的說明.
*
* @var string 這裡也可以放說明
*/
var $b ;
/**
* 這是針對函式的說明
* 也是一樣可以多行
* 若是簡單的範例也可以放這裡
*
* @param int $a 可以放入傳入的型態
* @return array 可以說明回傳的型態
*/
function first ( $a ) {
return array();
}
}
?>
基本上都是在
/*
*
*/
中間寫註解，別忘了每行前面要有個 * 喔!
註解比較常用到參數的應該是
@author 程式作者名稱，聯絡方式
@const 常數
@deprecate 不建議使用的 API
@global 全域變數
@param 函數的參數
@return 回傳值
@see 可參考函數
@since 開始時間
@static 靜態變數
@var 物件成員變數
@todo 計畫中要進行的項目
更多更詳細的資料請到 http://www.phpdoc.org/ 看囉!~
原文出處:http://blog.darkhero.net/?p=264
留言列表
Banana-Pi, 樹梅派應用 
