寫文件是一個程式設計師最最痛苦的事情之一,尤其是寫了一堆程式後有人要你把 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 


    全站熱搜

    Frank 發表在 痞客邦 留言(0) 人氣()