PHP Document 代碼注釋規範

PHPDocumentor是一個用PHP寫的工具，對于有規範注釋的php程式，它能夠快速生成具有互相參照,索引等功能的API文檔。老的版本是 phpdoc。

1. 什麼是phpDocumentor ?

PHPDocumentor是一個用PHP寫的工具，對于有規範注釋的php程式，它能夠快速生成具有互相參照,索引等功能的API文檔。老的版本是 phpdoc，從1.3.0開始，更名為phpDocumentor，新的版本加上了對php5文法的支援，同時，可以通過在用戶端浏覽器上操作生成文檔，文檔可以轉換為PDF,HTML,CHM幾種形式，非常的友善。

PHPDocumentor工作時，會掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取需要分析的注釋，然後分析注釋中的專用的tag，生成 xml檔案，接着根據已經分析完的類和子產品的資訊，建立相應的索引，生成xml檔案，對于生成的xml檔案，使用定制的模闆輸出為指定格式的檔案。

2. 安裝phpDocumentor

和其他pear下的子產品一樣，phpDocumentor的安裝也分為自動安裝和手動安裝兩種方式，兩種方式都非常友善：

a． 通過pear 自動安裝

在指令行下輸入

pear install PhpDocumentor

b． 手動安裝

在http://manual.phpdoc.org/下載下傳最新版本的PhpDocumentor（現在是1.4.0），把内容解壓即可。

3．怎樣使用PhpDocumentor生成文檔

指令行方式：

在phpDocumentor所在目錄下，輸入

Php –h

會得到一個詳細的參數表，其中幾個重要的參數如下：

-f 要進行分析的檔案名，多個檔案用逗号隔開

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

-t 生成的文檔的存放路徑

-o 輸出的文檔格式，結構為輸出格式：轉換器名：模闆目錄。

例如：phpdoc -o HTML:frames:earthli -f test.php -t docs

Web界面生成

在新的phpdoc中，除了在指令行下生成文檔外，還可以在用戶端浏覽器上操作生成文檔，具體方法是先把PhpDocumentor的内容放在apache目錄下使得通過浏覽器可以通路到，通路後顯示如下的界面：

點選files按鈕，選擇要處理的php檔案或檔案夾，還可以通過該指定該界面下的Files to ignore來忽略對某些檔案的處理。

然後點選output按鈕來選擇生成文檔的存放路徑和格式.

最後點選create，phpdocumentor就會自動開始生成文檔了，最下方會顯示生成的進度及狀态，如果成功，會顯示

Total Documentation Time: 1 seconds

done

Operation Completed!!

然後，我們就可以通過檢視生成的文檔了，如果是pdf格式的，名字預設為documentation.pdf。

4．給php代碼添加規範的注釋

PHPDocument是從你的源代碼的注釋中生成文檔，是以在給你的程式做注釋的過程，也就是你編制文檔的過程。

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

在phpdocumentor中，注釋分為文檔性注釋和非文檔性注釋。

所謂文檔性注釋，是那些放在特定關鍵字前面的多行注釋，特定關鍵字是指能夠被phpdoc分析的關鍵字，例如class，var等，具體的可參加附錄1.

那些沒有在關鍵字前面或者不規範的注釋就稱作非文檔性注釋，這些注釋将不會被phpdoc所分析，也不會出現在你産生的api文當中。

3.2如何書寫文檔性注釋:

所有的文檔性注釋都是由

function Add($a, $b) {

return $a+$b;

}

生成文檔如下：

Add

integer Add( int $a, int $b)

[line 45]

函數add,實作兩個數的加法

Constants 一個簡單的加法計算，函數接受兩個數a、b，傳回他們的和c

Parameters

• int $a - 加數

• int $b - 被加數

5．文檔标記：

文檔标記的使用範圍是指該标記可以用來修飾的關鍵字，或其他文檔标記。

所有的文檔标記都是在每一行的 * 後面以@開頭。如果在一段話的中間出來@的标記，這個标記将會被當做普通内容而被忽略掉。

@ access

使用範圍：class,function,var,define,module

該标記用于指明關鍵字的存取權限：private、public或proteced

@author

指明作者

@copyright

使用範圍：class，function，var，define，module，use

指明版權資訊

@deprecated

使用範圍：class，function，var，define，module，constent，global，include

指明不用或者廢棄的關鍵字

@example

該标記用于解析一段檔案内容，并将他們高亮顯示。Phpdoc會試圖從該标記給的檔案路徑中讀取檔案内容

@const

使用範圍：define

用來指明php中define的常量

@final

使用範圍：class,function,var

指明關鍵字是一個最終的類、方法、屬性，禁止派生、修改。

@filesource

和example類似，隻不過該标記将直接讀取目前解析的php檔案的内容并顯示。

@global

指明在此函數中引用的全局變量

@ingore

用于在文檔中忽略指定的關鍵字

@license

相當于html标簽中的<a>,首先是URL，接着是要顯示的内容

例如<a href=”http://www.baidu.com”>百度</a>

可以寫作 @license http://www.baidu.com 百度

@link

類似于license

但還可以通過link指到文檔中的任何一個關鍵字

@name

為關鍵字指定一個别名。

@package

使用範圍：頁面級别的-> define，function，include

類級别的->class，var，methods

用于邏輯上将一個或幾個關鍵字分到一組。

@abstrcut

說明目前類是一個抽象類

@param

指明一個函數的參數

@return

指明一個方法或函數的傳回指

@static

指明關建字是靜态的。

@var

指明變量類型

@version

指明版本資訊

@todo

指明應該改進或沒有實作的地方

@throws

指明此函數可能抛出的錯誤異常,極其發生的情況

上面提到過，普通的文檔标記标記必須在每行的開頭以@标記，除此之外，還有一種标記叫做inline tag,用{@}表示，具體包括以下幾種：

{@link}

用法同@link

{@source}

顯示一段函數或方法的内容

6．一些注釋規範

a.注釋必須是

的形式

b.對于引用了全局變量的函數，必須使用glboal标記。

c.對于變量，必須用var标記其類型（int,string,bool...）

d.函數必須通過param和return标記指明其參數和傳回值

e.對于出現兩次或兩次以上的關鍵字，要通過ingore忽略掉多餘的，隻保留一個即可

f.調用了其他函數或類的地方，要使用link或其他标記連結到相應的部分，便于文檔的閱讀。

g.必要的地方使用非文檔性注釋，提高代碼易讀性。

h.描述性内容盡量簡明扼要，盡可能使用短語而非句子。

i.全局變量，靜态變量和常量必須用相應标記說明