最近再總結一些PHP的規範, 想起之前在Y!的時候的API描述自動生成工具, 翻到了phpDocumentor, 用起來感覺還是很方便 , 就安裝到使用的過程寫下來, 與大家分享
phpDocumentor的安裝很簡單,
如果通過pear自動安裝
在命令行下輸入 pear install PhpDocumentor
如果是手動安裝
則在http://manual.phpdoc.org/下載最新版本的PhpDocumentor（現在是1.4.2），把內容解壓即可.
phpdocumentor的使用也很簡單, 分爲命令行模式和web模式:
命令行模式
在phpDocumentor所在目錄下，輸入
php –h
會得到一個詳細的參數表，其中幾個重要的參數如下：
-f 要進行分析的文件名，多個文件用逗號隔開
-d 要分析的目錄，多個目錄用逗號分割
-t 生成的文檔的存放路徑
-o 輸出的文檔格式，結構爲輸出格式：轉換器名：模板目錄。
例如：phpdoc -o HTML:frames:earthli -f test.php -t docs
Web模式
在新的phpdoc中，除了在命令行下生成文檔外，還可以在客戶端瀏覽器上操作生成文檔，具體方法是先把PhpDocumentor的內容放在 apache目錄下使得通過瀏覽器可以訪問到
點擊files按鈕，選擇要處理的php文件或文件夾，還可以通過該指定該界面下的Files to ignore來忽略對某些文件的處理。
然後點擊output按鈕來選擇生成文檔的存放路徑和格式.
最後點擊create，phpdocumentor就會自動開始生成文檔了，最下方會顯示生成的進度及狀態，如果成功，我們就可以通過查看生成的文檔了，如果是pdf格式的，名字默認爲documentation.pdf。
來看個例子:
代碼加上註釋:
- <?php
- /**
- * @filename baseTags.php
- * @touch date Tue 21 Apr 2009 11:49:12 AM CST
- * @package phpDocumentor demo
- * @author Laruence
- * @license http://www.zend.com/license/3_0.txt PHP License 3.0
- * @version 1.0.0
- * @copyright (c) 2009, Laruence
- */
- /**
- * this function is a demo to illustrate how phpdocument tags work
- * <code>
- * $bool = element(true, "laruence");
- * </code>
- * @deprecated
- * @param bool $bool a flag to decide whether the string should be output
- * @param string|int $string sometimes it's a string, sometimes it's a int
- * @return bool
- */
- function element($bool, $string){
- if ($bool){
- die("flag off");
- }
- echo "I love $string";
- return true;
- }
- ?>
在命令行模式下輸入:
phpdoc -o HTML:frames:default -f baseTags.php -t docs
還有一些其他技巧, 比如, 你可以把phpdoc這個腳本放到/usr/bin目錄下, 將phpdoc.ini和phpdocumentor目錄放到php設置的include path 下, 就可以把phpdoc當成shell命令來很方便的使用了.
還有, 比如一些文件的描述信息, 完全可以map成vim的一個宏命令, 我自己就把相關的信息都map成了F12,
- function MyCopy()
- call setline(line("."),"/**")
- call append(line(".")+1," * @filename ".expand("%"))
- call append(line(".")+2," * @touch date ".strftime("%c"))
- call append(line(".")+3," * @author Laruence<[email protected]>")
- call append(line(".")+4," * @license http://www.zend.com/license/3_0.txt PHP License 3.0")
- call append(line(".")+5," * @version 1.0.0 ")
- call append(line(".")+6,"*/")
- endf
- map <F12> <Esc>:call MyCopy()<CR><Esc>5j$a
等等.
最後, 生成的API文檔見這裏: 例子
如果有興趣, 還可以看看phpdoc的代碼, 也是很有意思,呵呵
