765
PHPDocumentor安裝與使用
PHPDocumentor 是一個用PHP寫的工具, 對於有規範注釋的php程序, 它能夠快速生成具有相互參照,索引等功能的API文檔.
安裝環境:
本機安裝的是 EasyPHP-5.3.2i 套件,
1 |
安裝目錄是 D:\Program Files\EasyPHP-5.3.2i\ |
2 |
php.exe 所在路徑是 D:\Program Files\EasyPHP-5.3.2i\php\php.exe |
首先安裝 PEAR:
1, 修改 D:\Program Files\EasyPHP-5.3.2i\php\go-pear.bat 內容如下:
1 |
@ECHO OFF |
2 |
set PHP_BIN=%CD%\php.exe |
3 |
"%PHP_BIN%" -d output_buffering=0 -d phar.require_hash=0 PEAR\go-pear.phar |
4 |
pause |
2, 開始->運行->cmd, 執行 go-pear.bat 開始安裝 Pear, 一路回車
1 |
Microsoft Windows XP [版本 5.1.2600] |
2 |
(C) 版權所有 1985-2001 Microsoft Corp. |
3 |
4 |
C:\Documents and Settings\kuco>D: |
5 |
6 |
D:\>cd D:\Program Files\EasyPHP-5.3.2i\php |
7 |
8 |
D:\Program Files\EasyPHP-5.3.2i\php>go-pear.bat |
3, 修改 php.ini 中的 include_path
1 |
include_path = ".;${path}\php\includes;${path}\php\PEAR" |
4, EasyPHP 套件中的 php.ini 沒有存放在 php.exe 所以目錄中,所以要複製一份.
1 |
複製 D:\Program Files\EasyPHP-5.3.2i\apache\php.ini |
2 |
到 D:\Program Files\EasyPHP-5.3.2i\php\ 目錄下
|
開始安裝 PhpDocumentor:
5, 安裝 PhpDocumentor 依賴包 XML_Parser
1 |
D:\Program Files\EasyPHP-5.3.2i\php>pear install XML_Parser |
2 |
downloading XML_Parser-1.3.4.tgz ... |
3 |
Starting to download XML_Parser-1.3.4.tgz (16,040 bytes) |
4 |
......done: 16,040 bytes |
5 |
install ok: |
6, 安裝 PhpDocumentor
1 |
D:\Program Files\EasyPHP-5.3.2i\php>pear install PhpDocumentor |
2 |
Did not download optional dependencies: pear/XML_Beautifier, use --alldeps to do |
3 |
wnload automatically |
4 |
pear/PhpDocumentor can optionally use package "pear/XML_Beautifier" (version >= |
5 |
1.1) |
6 |
downloading PhpDocumentor-1.4.3.tgz ... |
7 |
Starting to download PhpDocumentor-1.4.3.tgz (2,423,486 bytes) |
8 |
......done: 2,423,486 bytes |
9 |
install ok: |
使用 PhpDocumentor 生成注釋文檔
7, 假設我們要給 Smarty 的源碼包生成一個注釋文檔
1 |
Smarty 源碼存放目錄為: E:\www\IDE\Smarty\libs\ |
2 |
注釋文檔存放的目錄為: E:\www\IDE\doc |
3 |
開始在命令行執行命令: |
4 |
D:\Program Files\EasyPHP-5.3.2i\php>phpdoc.bat -o HTML:Smarty:PHP -d E:\www\IDE\Smarty\libs\ -t E:\www\IDE\doc |
可以通過下麵的命令得到更多的幫助說明
1 |
D:\Program Files\EasyPHP-5.3.2i\php>phpdoc -h |
在phpdoc.bat所在目錄下，輸入
Phpdoc –h
會得到一個phpDocumentor的詳細參數列表。
我們從其中選出幾個常用的來看看：
〈? 命令解釋 ?〉
-f
要進行分析的文件名，多個文件用逗號分割
-d
要分析的目錄，多個目錄用逗號分割
-t
生成的文檔的存放路徑
-o
輸出的文檔格式，結構為輸出格式:轉換器名:模版目錄，例如：HTML:frames:phpedit
我們會用到的就這幾個了，其他的命令請大家閱讀help的提示信息。
試用phpDocumentor
下麵我們就以pear中的phpUnit2為例，演示一下如何使用phpDocumentor來生成文檔。
首先，把我們需要的參數確定下來：
〈? 命令參數 ?〉
-d
C:Program FilesEasyPHP5phpPEARPHPUnit2
-t
C:Program FilesEasyPHP5phpphpunit2doc
-o
HTML:frames:phpedit
根據上邊的參數，我們組合出下邊的命令：
Phpdoc -d “C:\Program Files\EasyPHP5\php\PEAR\PHPUnit2” -t “C:\Program Files\EasyPHP5\php\phpunit2doc” -o “HTML:frames:phpedit”
運行上邊的命令後，phpDocumentor開始解析源文件並輸出工作信息。
命令運行完成後，我們的文檔就已經生成好了。 進入我們指定的目標目錄，用瀏覽器打開index.html就可以看見生成的文檔了。 文檔界麵由frame分成了三個部分，左上是包信息，左下是導航信息，右邊則是詳細的信息呈現頁。
上邊的圖很清楚地描述出了文檔的內容：
索引、函數列表、類列表、文件列表和子包。
點擊上邊的class(es)鏈接，我們可以清晰的看見整個包的class tree。
我們點擊其中一個class，就進入了class的描述頁麵。
Class描述頁麵主要包含以下幾方麵內容：
l 描述：版權、作者、類層次等
l 類變量
l 類常量
l 方法
l 繼承的變量
l 繼承的方法：非常有用的一個功能
怎麼樣，是不是很詳細呢？如果要生成chm，可以把前邊的-o參數改為”CHM:default: default”，這樣phpDocumentor會為你生成好chm項目文件，隻要用微軟的chm工具進行編譯就可以得到可用的chm文件了。
用phpDocumentor為自己的代碼生成文檔
雖然phpDocumentor可以自動從代碼中分析出一些信息，但是，要形成一份詳盡的文檔還是需要我們在編碼中進行配合的。為了讓phpDocumentor讀懂我們的代碼，我們需要注意一些編碼規範和在注釋中增加一些tag：
〈? Tags ?〉
@author
作者信息
@const
由define定義的常量
@deprecate
不建議使用的API
@global
全局變量
@package
包信息
@param
函數參數
@return
返回值
@see
參考函數
@since
引入時間
@static
靜態變量
@var
類成員變量
這裏隻是簡單的列出了常用的一些Tag，大家可以閱讀phpDocumentor的文檔，裏邊有非常詳細的編碼規範。關於phpDocumento就介紹到這裏，希望大家都能好好利用這個工具來規範自己的文檔。
PS：phpDocumentor也有Web界麵的，你可以訪問https://phpdoc.org獲取Web版本。Web版本的安裝很簡單，直接放到web可以訪問的目錄就可以運行了。
〈? 環境要求 ?〉
最後更新：2017-04-03 16:48:33