關於PHPDocument 代碼注釋規範的總結

1. 安裝phpDocumentor（不推薦命令行安裝）

在http://manual.phpdoc.org/下載最新版本的PhpDoc

放在web伺服器目錄下使得通過瀏覽器可以訪問到

點擊files按鈕，選擇要處理的php文件或文件夾

還可以通過該指定該界面下的Files to ignore來忽略對某些文件的處理。

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

最後點擊create，phpdocumentor就會自動開始生成文檔了。

2．如何寫PHP規範注釋

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

@access 該標記用於指明關鍵字的存取許可權：private、public或proteced 使用範圍：class,function,var,define,module

@author 指明作者

@copyright 指明版權信息

@const 使用範圍：define 用來指明php中define的常量

@final 使用範圍：class,function,var 指明關鍵字是一個最終的類、方法、屬性，禁止派生、修改。

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

@name 為關鍵字指定一個別名。

@package 用於邏輯上將一個或幾個關鍵字分到一組。

@abstrcut 說明當前類是一個抽象類

@param 指明一個函數的參數

@return 指明一個方法或函數的返回值

@static 指明關建字是靜態的。

@var 指明變數類型

@version 指明版本信息

@todo 指明應該改進或沒有實現的地方

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

@ingore 用於在文檔中忽略指定的關鍵字

一些注釋規範

a.注釋必須是

/**

* XXXXXXX

*/

的形式

b.對於引用了全局變數的函數，必須使用glboal標記。

c.對於變數，必須用var標記其類型（int,string,bool...）

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

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

f.調用了其他函數或類的地方，要使用link或其他標記鏈接到相應的部分，便於文檔的閱讀。

g.必要的地方使用非文檔性注釋（PHPDOC無法識別的關鍵字前的注釋），提高代碼易讀性。

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

i.全局變數，靜態變數和常量必須用相應標記說明

能夠被phpdoc識別的關鍵字：

Include

Require

include_once

require_once

define

function

global

class

3. 規範注釋的php代碼 :

<?phpn/**n* 文件名(sample2.php)n*n* 功能描述（略）n*n* @author steve <http://www.jb51.net>n* @version 1.0n* @package sample2n*/n/**n* 包含文件n*/ninclude_once sample3.php;n/**n* 聲明全局變數n* @global integer $GLOBALS[_myvar]n* @name $_myvarn*/n$GLOBALS[_myvar] = 6;n/**n* 聲明全局常量n*/ndefine(NUM, 6);n/**n* 類名n*n* 類功能描述n*n* @package sample2n* @subpackage classes(如果是父類 就添加)n*/nclass myclass {n/**n* 聲明普通變數n*n* @accessprivaten* @var integer|stringn*/nvar $firstvar = 6;n/**n* 創建構造函數 {@link $firstvar}n*/nfunction myclass() {n$this->firstvar = 7;n}n/**n* 定義函數n*n* 函數功能描述n*n* @global string $_myvarn* @staticvar integer $staticvarn* @param string $param1n* @param string $param2n* @return integer|stringn*/nfunction firstFunc($param1, $param2 = optional) {n static $staticvar = 7;n global $_myvar;n return $staticvar;n }n}n?>n

推薦閱讀：