註釋標籤在程式碼註釋中的作用非常大，好的找註釋標籤可以讓你在程式設計過程中有更好、更舒適的體驗，所以我今天準備整理一下這些標記，透過圖文的形式展示出來，一方面是為了自己對這些註釋標籤有一個彙總整理，另一方面也希望大家能夠更好對理解註釋標籤
每個人都希望寫出漂亮的程式碼，或許你離漂亮的程式碼，就差一個標籤
| 標記 | 用途 | 描述 |
|---|---|---|
| @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 [Type] [name] [<description>]\
例如@param string title 文章標題
程式碼舉例
說明
返回值
格式@return [型別] [<描述>]]
例如@return array 結果陣列
程式碼舉例
說明
不建議使用的、已過期的、將被刪除的\
格式@deprecated [<版本號>] [<描述>]\
例如@deprecated 1.0.0 新版本將不再包含此函式\
如果它是被其他方法所取代了，建議新增@see標記
程式碼舉例
說明
參考，類似@link，可與@deprecated聯動
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tableName() 舊方法table_name已棄用，請使用此方法替代
程式碼舉例
說明
連結，可用於輔助說明、引用文件等\
格式@link [url] [<描述>]\
例如@link http://g.cn 不懂滾去問谷歌，別來煩我
程式碼舉例
| - | @see | @link |
|---|---|---|
| 外部連結 | √ | √ |
| 內部程式 | √ | X |
說明
變數\
格式@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 | 當前例項 |
程式碼舉例
1、在方法外的變數定義
2、在方法內的變數定義
說明
可能會丟擲的錯誤型別\
格式@throws [型別] [<描述>]\
例如@throws Exception
本作品採用《CC 協議》，轉載必須註明作者和本文連結