PhpDocumentor

phpDocumentor

phpDocumentor，是一個(gè)用PHP寫(xiě)的工具，對(duì)于有規(guī)范注釋的php程序，它能夠快速生成具有相互參照,索引等功能的API文檔。老的版本是 phpdoc，從1.3.0開(kāi)始，更名為phpDocumentor，新的版本加上了對(duì)php5語(yǔ)法的支持，同時(shí)，可以通過(guò)在客戶端瀏覽器上操作生成文檔，文檔可以轉(zhuǎn)換為PDF,HTML,CHM幾種形式。

通過(guò)讀取名為文檔塊(DocBlocks)的特殊的PHP注釋，phpDocumentor生成手冊(cè)格式的文檔。文檔塊是軟件項(xiàng)目的作者應(yīng)該為有用信息作注釋的地方，它能夠被其他人使用(未來(lái)你自己也可能用到)，以確定如何使用和擴(kuò)展你的PHP包。

盡管在源代碼中添加簡(jiǎn)潔文檔的能力是基本的，但它不能代替源代碼之外的詳細(xì)文檔的重要性，例如用戶手冊(cè)或你正在閱讀的這個(gè)指南。如果你現(xiàn)在閱讀的這些文本是放在源代碼中供phpDocumentor使用的，那它的實(shí)用性就會(huì)變得很小，因?yàn)檫@不僅使代碼顯得混亂，而且文本本身也很難查找。然而，在源代碼中的文檔和外部文檔之間創(chuàng)建超鏈接的能力是基本的。函數(shù)foo的外部文檔必須能夠參考代碼中生成的文檔，有了phpDocumentor這一切終于成為可能。

目錄

• 1 phpDocumentor工作流程
• 2 phpDocumentor安裝
• 3 phpDocumentor相關(guān)資源
• 4 相關(guān)條目
• 5 參考來(lái)源

phpDocumentor工作流程

PHPDocumentor工作時(shí)，會(huì)掃描指定目錄下面的php源代碼，掃描其中的關(guān)鍵字，截取需要分析的注釋，然后分析注釋中的專用的tag，生成 xml文件，接著根據(jù)已經(jīng)分析完的類(lèi)和模塊的信息，建立相應(yīng)的索引，生成xml文件，對(duì)于生成的xml文件，使用定制的模板輸出為指定格式的文件。

phpDocumentor安裝

官方提供了兩種phpDocumentor的安裝方法。第一種方法是從pear.php.net和sourceforge.net下載和解壓縮任一可用的檔案，另一種方法是通過(guò)PEAR安裝工具安裝。已有一個(gè)名為“Phing任務(wù)”的計(jì)劃，準(zhǔn)備通過(guò)其它新的有前途的安裝框架來(lái)分發(fā)，例如ZZ/OS安裝工具。然而，phpDocumentor的開(kāi)發(fā)者只為上述兩種官方的安裝方法提供支持。

• 從Pear.Php.net或Sourceforge.net下載

在從pear.php.net或sourdeforge.net下載.zip或tar包來(lái)安裝phpDocumentor之前，請(qǐng)先確認(rèn)你要使用 phpDocumentor的Web界面還是命令行界面(參考“phpDocumentor工具的基本用法”一節(jié)來(lái)幫助你做這個(gè)決定)。

如果想要使用命令行界面，把文檔解壓到任意一個(gè)目錄，比如/home/myuser/phpdoc或C:\Program Files\phpdoc，然后把目錄添加到你的path語(yǔ)句。運(yùn)行“phpdoc”命令來(lái)使用它。在Windows中，你需要編輯phpdoc.bat 文件，把第一行改為PHP的CLI版本的路徑(默認(rèn)情況下通常是C:\php4\cli\php.exe)。

如果想要使用Web界面，你必須安裝Web服務(wù)器，例如Apache，這個(gè)Web服務(wù)器必須有能工作的PHP sapi。為了測(cè)試這一點(diǎn)，把下面的代碼([code]和[/code]之間的內(nèi)容)保存為phpinfo.php，把這個(gè)文件放到Web服務(wù)器的根目錄下，瀏覽http://localhost/phpinfo.php。

phpinfo.php:
[code]
       <?php
       phpinfo();
       ?>
[/code]

如果你看到漂亮的PHP信息顯示出來(lái)，那么你的PHP安裝就是能工作的。要使用phpDocumentor的Web界面，只要簡(jiǎn)單地把檔案解壓縮到Web 服務(wù)器根目錄的一個(gè)子目錄(例如phpdoc)，然后瀏覽那個(gè)位置(http://localhost/phpdoc)。

要觀看更新的Web界面，需要一個(gè)支持Javascript的瀏覽器，例如Netscape、Mozilla、Internet Explorer、Opera或Konqueror。如果你想要使用不支持Javascript的瀏覽器，例如links/lynx，請(qǐng)使用舊的Web界面，phpdoc.php，它位于http://localhost/phpdoc/phpdoc.php。

• 從PEAR安裝

要從PEAR安裝phpDocumentor，你首先必須有一個(gè)能夠工作的安裝好的PEAR。關(guān)于正確安裝PEAR的操作指南位于PEAR的官方網(wǎng)站(http://pear.php.net)。phpDocumentor的開(kāi)發(fā)者不對(duì)PEAR的安裝問(wèn)題提供支持，作為替代的，請(qǐng)從PEAR的開(kāi)發(fā)者那里尋求幫助。

安裝命令行的phpDocumentor非常簡(jiǎn)單，運(yùn)行：

$ pear install PhpDocumentor

然后你就可以完全訪問(wèn)phpdoc命令了，不管是在Windows下還是Linux下，不需要進(jìn)一步配置。

安裝使用Web界面的phpDocumentor，首先你必須修改PEAR的配置變量data_dir，把它指向你的Web服務(wù)器根目錄的一個(gè)子目錄。完成這項(xiàng)工作的最簡(jiǎn)單的辦法是通過(guò)PEAR的命令行界面運(yùn)行：

 $ pear config-set data_dir /path/to/document_root/pear

從Web界面來(lái)配置這個(gè)值也很簡(jiǎn)單。單擊左邊幀里的配置圖標(biāo)，在data_dir文本框中鍵入地址。(這個(gè)Web界面的入口在哪里我也沒(méi)有搞清楚，不過(guò)從命令行配置確實(shí)是一個(gè)好辦法)

一旦配置完成，使用上面第二段中的命令就可以簡(jiǎn)單地安裝phpDocumentor，然后你可以瀏覽http://localhost/pear/PhpDocumentor來(lái)訪問(wèn)Web界面。一旦這步配置完成，就無(wú)須再做改變，通過(guò)使用pear的upgrade命令你可以毫不費(fèi)力地升級(jí)到未來(lái)的 phpDocumentor版本。

phpDocumentor相關(guān)資源

官方網(wǎng)站 ｜ 最新官方下載

相關(guān)條目

• PHP

參考來(lái)源

• 參考來(lái)源1
• 參考來(lái)源2