php安装与使用,安装与使用phpDocument

寫文件是一個程式設計師最最痛苦的事情之一，尤其是寫了一堆程式後有人要你把

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

的註解有一定的規格，但是都跟我們原來寫註解的方式很像，只是要注意一下東西而已。

簡單的來看個範例好了

class MyClass {

var $a

;

var $b

;

function

first ( $a ) {

return array();

}

}

?>

基本上都是在

中間寫註解，別忘了每行前面要有個 * 喔!

註解比較常用到參數的應該是

@author 程式作者名稱，聯絡方式

@const 常數

@deprecate 不建議使用的 API

@global 全域變數

@param 函數的參數

@return 回傳值

@see 可參考函數

@since 開始時間

@static 靜態變數

@var 物件成員變數

@todo 計畫中要進行的項目