PHPDocumentor安裝與使用

phpdocumentor 是一個用php寫的工具, 對于有規範注釋的php程式, 它能夠快速生成具有互相參照,索引等功能的api文檔.

安裝環境:

本機安裝的是 easyphp-5.3.2i 套件,

<code>1</code>

<code>安裝目錄是 d:\program files\easyphp-5.3.2i\</code>

<code>2</code>

<code>php.exe 所在路徑是 d:\program files\easyphp-5.3.2i\php\php.exe</code>

首先安裝 pear:

1, 修改 d:\program files\easyphp-5.3.2i\php\go-pear.bat 内容如下:

<code>@echo off</code>

<code>set php_bin=%cd%\php.exe</code>

<code>3</code>

<code>"%php_bin%" -d output_buffering=0 -d phar.require_hash=0 pear\go-pear.phar</code>

<code>4</code>

<code>pause</code>

2, 開始-&gt;運作-&gt;cmd, 執行 go-pear.bat 開始安裝 pear, 一路回車

<code>microsoft windows xp [版本 5.1.2600]</code>

<code>(c) 版權所有 1985-2001 microsoft corp.</code>

<code>c:\documents and settings\kuco&gt;d:</code>

<code>5</code>

<code>6</code>

<code>d:\&gt;cd d:\program files\easyphp-5.3.2i\php</code>

<code>7</code>

<code>8</code>

<code>d:\program files\easyphp-5.3.2i\php&gt;go-pear.bat</code>

3, 修改 php.ini 中的 include_path

<code>include_path = ".;${path}\php\includes;${path}\php\pear"</code>

4, easyphp 套件中的 php.ini 沒有存放在 php.exe 是以目錄中,是以要複制一份.

<code>複制 d:\program files\easyphp-5.3.2i\apache\php.ini</code>

<code>  </code><code>到 d:\program files\easyphp-5.3.2i\php\ 目錄下</code>

開始安裝 phpdocumentor:

5, 安裝 phpdocumentor 依賴包 xml_parser

<code>d:\program files\easyphp-5.3.2i\php&gt;pear install xml_parser</code>

<code>downloading xml_parser-1.3.4.tgz ...</code>

<code>starting to download xml_parser-1.3.4.tgz (16,040 bytes)</code>

<code>......done: 16,040 bytes</code>

<code>install ok: </code>

6, 安裝 phpdocumentor

<code>d:\program files\easyphp-5.3.2i\php&gt;pear install phpdocumentor</code>

<code>did not download optional dependencies: pear/xml_beautifier, use --alldeps to do</code>

<code>wnload automatically</code>

<code>pear/phpdocumentor can optionally use package "pear/xml_beautifier" (version &gt;=</code>

<code>1.1)</code>

<code>downloading phpdocumentor-1.4.3.tgz ...</code>

<code>starting to download phpdocumentor-1.4.3.tgz (2,423,486 bytes)</code>

<code>......done: 2,423,486 bytes</code>

<code>9</code>

使用 phpdocumentor 生成注釋文檔

7, 假設我們要給 smarty 的源碼包生成一個注釋文檔

<code>smarty 源碼存放目錄為: e:\www\ide\smarty\libs\</code>

<code>注釋文檔存放的目錄為: e:\www\ide\doc</code>

<code>開始在指令行執行指令:</code>

<code>d:\program files\easyphp-5.3.2i\php&gt;phpdoc.bat -o html:smarty:php -d e:\www\ide\smarty\libs\ -t e:\www\ide\doc</code>

可以通過下面的指令得到更多的幫助說明

<code>d:\program files\easyphp-5.3.2i\php&gt;phpdoc -h</code>

在phpdoc.bat所在目錄下，輸入

phpdoc –h

會得到一個phpdocumentor的詳細參數清單。

我們從其中選出幾個常用的來看看：

〈? 指令解釋 ?〉

-f 

要進行分析的檔案名，多個檔案用逗号分割

-d 

要分析的目錄，多個目錄用逗号分割

-t 

生成的文檔的存放路徑

-o 

輸出的文檔格式，結構為輸出格式:轉換器名:模版目錄，例如：html:frames:phpedit  

我們會用到的就這幾個了，其他的指令請大家閱讀help的提示資訊。

試用phpdocumentor

下面我們就以pear中的phpunit2為例，示範一下如何使用phpdocumentor來生成文檔。

首先，把我們需要的參數确定下來：

〈? 指令參數 ?〉

c:program fileseasyphp5phppearphpunit2

c:program fileseasyphp5phpphpunit2doc

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就介紹到這裡，希望大家都能好好利用這個工具來規範自己的文檔。

〈? 環境要求 ?〉