每一個 PHPer 都應當掌握的註釋標記(轉)

前言

註釋標籤在代碼註釋中的做用很是大，好的找註釋標籤可讓你在編程過程當中有更好、更溫馨的體驗，因此我今天準備整理一下這些標記，經過圖文的形式展現出來，一方面是爲了本身對這些註釋標籤有一個彙總整理，另外一方面也但願你們可以更好對理解註釋標籤

每一個人都但願寫出漂亮的代碼，或許你離漂亮的代碼，就差一個標籤

經常使用標籤

標記	用途	描述
@abstract		抽象類的變量和方法
@access	public, private or protected	文檔的訪問、使用權限. @access private 代表這個文檔是被保護的。
@author	張三 zhangsan@163.com	文檔做者
@copyright	名稱 時間	文檔版權信息
@deprecated	version	文檔中被廢除的方法
@deprec		同 @deprecated
@example	/path/to/example	文檔的外部保存的示例文件的位置。
@exception		文檔中方法拋出的異常，也可參照 @throws.
@global	類型：$globalvarname	文檔中的全局變量及有關的方法和函數
@ignore		忽略文檔中指定的關鍵字
@internal		開發團隊內部信息
@link	URL	相似於 license 但還能夠經過 link 找到文檔中的更多個詳細的信息
@name	變量別名	爲某個變量指定別名
@magic		phpdoc.de compatibility
@package	封裝包的名稱	一組相關類、函數封裝的包名稱
@param	如 $username 用戶名	變量含義註釋
@return	如 返回 bool	函數返回結果描述，通常不用在 void（空返回結果的）的函數中
@see	如 Class Login ()	文件關聯的任何元素（全局變量，包括，頁面，類，函數，定義，方法，變量）。
@since	version	記錄何時對文檔的哪些部分進行了更改
@static		記錄靜態類、方法
@staticvar		在類、函數中使用的靜態變量
@subpackage		子版本
@throws		某一方法拋出的異常
@todo		表示文件未完成或者要完善的地方
@var	type	文檔中的變量及其類型
@version		文檔、類、函數的版本信息

上面這麼多其實很大一部分都是建立文件、建立類的時候須要添加的。今天主要講解一下經常使用的標籤。

@param

說明

參數，用於函數和方法註釋裏的標記 \
格式 @param [Type] [name] [<description>]\
例如 @param string title 文章標題

代碼舉例

@return

說明

返回值
格式 @return [類型] [< 描述 >]]
例如 @return array 結果數組

代碼舉例

@deprecated

說明

不建議使用的、已過時的、將被刪除的 \
格式 @deprecated [<版本號>] [<描述>]\
例如 @deprecated 1.0.0 新版本將再也不包含此函數 \
若是它是被其餘方法所取代了，建議添加 @see 標記

代碼舉例

@see

說明

參考，相似 @link，可與 @deprecated 聯動
格式 @see [url 或完整方法名] [< 描述 >]
例如 @see \yii\base\db::tableName () 舊方法 table_name 已棄用，請使用此方法替代

代碼舉例

@link

說明

連接，可用於輔助說明、引用文檔等 \
格式 @link [url] [<描述>]\
例如 @link http://g.cn 不懂滾去問谷歌，別來煩我

代碼舉例

@link&@see 區別

-	@see	@link
外部連接	√	√
內部程序	√	X

@var

說明

變量 \
格式 @var [類型] [變量名] [<描述>]\
例如 @var int id 用戶id

變量列表

變量類型	說明
string	字符串
integer/int	number/int 類型
boolean/bool	false/true
float/double	number / 浮點數
object	對象實例
specifiedType	指定類
mixed	任意類型
array/specifiedType[]	數組，能夠指定成指定類型的數組
resource	文件資源類型
void	無返回值
null	-
callable	可執行的回調函數
function	不必定能執行的方法
self/$this	當前實例

代碼舉例

一、在方法外的變量定義

二、在方法內的變量定義

@throws

說明

可能會拋出的錯誤類型 \
格式 @throws [類型] [<描述>]\
例如 @throws Exception