如何寫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

規範註釋的php代碼 :

<?php  
	/** 
	* 文件名(sample2.php) 
	* 
	* 功能描述（略） 
	* 
	* @author steve <liuzhiqun@facedoing.com> 
	* @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;  
		}
}  
?>