PHPDocumentor安裝與使用）

PHPDocumentor安裝與使用By kuco |Published:
2011/04/07

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: channel://pear.php.net/XML_Parser-1.3.4

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: channel://pear.php.net/PhpDocumentor-1.4.3

使用 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介面的，你可以訪問http://phpdoc.org擷取Web版本。Web版本的安裝很簡單，直接放到web可以訪問的目錄就可以運行了。

 

〈? 環境要求 ?〉