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

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代碼 :
/**
* 檔案名稱(sample2.php)
*
* 功能描述（略）
*
* @author steve
* @version 1.0
* @package sample2
*/
/**
* 包含檔案
*/
include_once 'sample3.php';
/**
* 聲明全域變數
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* 聲明全域常量
*/
define('NUM', 6);
/**
* 類名
*
* 類功能描述
*
* @package sample2
* @subpackage classes(如果是父類 就添加)
*/
class myclass {
/**
* 聲明普通變數
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* 建立建構函式 {@link $firstvar}
*/
function myclass() {
$this->firstvar = 7;
}
/**
* 定義函數
*
* 函數功能描述
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param1
* @param string $param2
* @return integer|string
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
}
?>

http://www.bkjia.com/PHPjc/327853.htmlwww.bkjia.comtruehttp://www.bkjia.com/PHPjc/327853.htmlTechArticle1. 安裝phpDocumentor（不推薦命令列安裝） 在http://manual.phpdoc.org/下載最新版本的PhpDoc 放在web伺服器目錄下使得通過瀏覽器可以訪問到 點擊f...

