phpdoc

phpdoc,計算機語言函式,見於PHP語言。

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為你工作了。

相關詞條

相關搜尋

熱門詞條

聯絡我們