phpdoc

1. 什麼是phpdoc

PHPDoc是PEAR下面的一個非常優秀的模塊，它的目標是實現類似javadoc的功能，可以為你的代碼快速生成具有相互參照，索引等功能的API文檔。如果你使用過javadoc生成的文檔(如jdk的文檔），你會非常清楚.

2. phpdoc的結構及功能

由於phpdoc本身也是符合pear的應用程序，我們首先了解一下它的結構。phpdoc是全部採用OOP的思想來編寫的，這也是PEAR所推薦的方式,phpdoc的工作原理：

1. phpdoc掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取需要分析的註釋，然後分析註釋中的專用的tag，生成xml文件，接著根據已經分析完的類和模塊的信息，建立相應的索引，生成xml文件

2. 對於生成的xml文件，使用定製的模板輸出為html文件。

從設計上來說，phpdoc使用了2個超類：PhpdocObject和PhpdocError。這是整個PHPDOC的基本類，這種方式也是PEAR所推薦的，也就是說當你編寫你自己的應用框架的時候，最好能夠有一個基本的超類，而其他的子類或者是功能類都有一個共同的祖先。在掃描源代碼過程中，PHPDOC使用的是類似GREP的形式，並沒有象我們通常想的那樣，使用正則表達式來實現，根據作者的解釋，他曾經嘗試過使用正則表達式，但是資源的佔用和處理速度都很難令人滿意，因此採用了這種非常規的形式，具體的實現有興趣的讀者可以參看源代碼。我認為PHPDOC令人滿意的另一方面是其分析結果是以XML形式保存的，這樣就意味著其他的應用程序很容易可以共享這個數據，同時PHPDCO也提供了相應的介面，你可以實現這個介面，把API文檔生成其他的形式，比如PDF，LATEX，WORD等等。目前，PHPDOC的分析結果可以以HTML形式表現，以後可能會有更多的形式。即使是HTML形式，由於使用了模板機制（他使用了PEAR的IT和ITX模塊來實現），你可以很方便地定製成你自己需要的風格.

3. PHPDoc基礎

PHPDoc是從你的源代碼的註釋中生成文檔，因此在給你的程序做註釋的過程，也就是你編製文檔的過程。

從這一點上講，PHPdoc促使你要養成良好的編程習慣，盡量使用規範，清晰文字為你的程序做註釋，同時多多少少也避免了事後編製文檔和文檔的更新不同步的一些問題。

編製符合PHPDoc規範的註釋是非常重要的，掌握了這一點，基本上就可以利用PHPDoc為你工作了。