[PHP] 註解規則表 – PHP Comment

以下為PHP註解規格,可用於宣告變數(Variable)、方法函數(Function)或類別(Class)中:

/**
 *  函數名稱
 *  函數描述(有些會含HTML代碼)
 *
 * @access   		變數可存取的權限 (Example: Public or Private)
 * @api    		爲第三方來源的變數
 * @author   		函數建立者名稱 (Example: @author Nick Tsai )
 * @category  		函數的分類別名,可能某些工具會利用這個來分類你的方法,使好幾個方法歸為某一類,方便做辨識使用
 * @copyright   	函數的版權宣告 (Example: @copyright Code.YIDAS code.yidas.com)
 * @deprecated  	代表不建議使用的函數,未來可能會移除這個方法使用到的某個變數,或整個方法都被刪除
 * @example   		代表這個函數使用方式可以參考某個資料,可以使用檔案位置或網址 (Example: @example http://code.yidas.com/)
 * @filesource  	這個函數所需的來源
 * @global   		函數內有使用的全域變數註解 (Example: @global Integer $user_id)
 * @ignore   		代表這個函數或區域可以被忽略,通常會加上說明
 * @internal       	代表這個函數或區域可能只給予內部使用
 * @license   		此函數可能是含有某個版權或許可 (Example: @license http://opensource.org/licenses/gpl-license.php GNU Public License)
 * @link    		可能與某個網站有關係 (Example: @link http://code.yidas.com/)
 * @method   		函數有使用的方法 (Example: @method Array @this->getCategories() or @method String getUserName())
 * @package   		利用這個註解來達到細部分層結構 (Example: @package PSR\Documentation\API or @package PSR\Documentation\Doc)
 * @param    		函數要帶入的參數 (Example: @param String|Integer $username)
 * @property       	如果這是一個類別的函數,在類別建構時通常會指定初始化參數,而這個函數可能會使用到某些初始化後的參數,稱之為屬性 (Example: @property Resource|Boolean $mysql_connect)
 * @return   		函數最後的回傳值或形態 (Example: @return Array|Object|Boolean)
 * @see    		函數參照或關聯的方法 (Example: @see Class User or @see Code.YIDAS)
 * @since    		函數內某個使用的變數由哪個版本變動 (Example: @since v1.3.5 $user_nickname )
 * @source   		這個比較特別,在函數中可以標示從 m 至 n 行 是做什麼事情 (Example: @source 14 21 Get user data)
 * @static   		靜態變數的註解 (Example: @static String $lang = 'zh_TW')
 * @subpackage  	利用這個註解來達到細部分層子結構,通常會同時使用 @package,可以參考上面的@package (Example: @package PSR @subpackage Documentation\API)
 * @throws   		例外處理的註解,有多種例外處理的方式,每種方式都不同 (Example: @throws InvalidArgumentException if the provided argument is not of type 'array'
 * @todo    		計劃要進行的項目描述,一般應該會使用文字描述
 * @uses    		代表某個元素可能與其它結構有利用關係 (Example: @uses MyClass::$items to retrieve the count from)
 * @var    		變數(物件成員變數)的形態或描述 (Example: @var Boolean)
 * @version   		函數的版本 (Example: v1.3.2)
 */

參考:http://www.barryblogs.com/php-comment-rules/

Leave a Reply

Your email address will not be published. Required fields are marked *