什么是注釋標記
我們在平常寫代碼或看別人寫的代碼時, 在方法的說明注釋中經常會有這樣的注釋:
/**
* @param $num
* @return array
*/
上面的@param @return 就是注釋標記
注釋標記用於生成文檔, param指明需要接收的參數, return指明返回值
在使用 phpDocumentor 等工具生成文檔時, 會識別相關注釋, 而且IDE也會識別, 在編碼的過程中會給出提示.
PHP注釋標記總結
- @api: 提供給第三方使用的接口
- @author: 標明作者
- @param: 參數
- @return: 返回值
- @todo: 待辦
- @version: 版本號
- @inheritdoc: 文檔繼承
- @property: 類屬性
- @property-read: 只讀屬性
- @property-write: 只寫屬性
- @const: 常量
- @deprecated: 過期方法
- @example: 示例
- @final: 標識類是終態, 禁止派生
- @global: 指明引用的全局變量
- @static: 標識類、方法、屬性是靜態的
- @ignore: 忽略
- @internal: 限內部使用
- @license: 協議
- @link: 鏈接,引用文檔等
- @see: 與 link 類似, 可以訪問內部方法或類
- @method: 方法
- @package: 命名空間
- @since: 從指定版本開始的變動
- @throws: 拋出異常
- @uses: 使用
- @var: 變量
- @copyright: 版權聲明
@author
標明作者
/*
* @author hujing <hu@163.com>
* hujing: 作者名
* hu@163.com: 郵箱
*/
@copyright
版權聲明
@copyright [描述]
@deprecated
標明方法是不建議使用的、已過期的或將要刪除的
/*
* 語法:
* @deprecated [版本號] [描述]
* eg:
* @see Class::test()
* @deprecated 2.0 將被棄用,請使用test方法
*/
@inheritdoc
會繼承父類文檔, 且子類出現沖突文檔時重寫父類文檔
@internal
標識此類或方法僅限當前文件使用
@description [描述]
@link
指明外部鏈接, 必須給出完整url
@link [url] [描述]
@see
此鏈接不光可以跳轉到外部鏈接, 還可以跳轉到內部的指定方法等, 如: class::method
@see [url|內部方法] [描述]
@var
定義數據的類型
@var [類型] [變量名] [描述]
/**
* 可以指定變量的類型
* @var array 名稱列表
* 也可以指定變量名, 指定變量時數組或空
* @var array|null $nameList 名稱列表
*/
類型列表如下:
- string: 字符串
- int/integer: 數字
- boolean/bool: 布爾
- float/double: 浮點
- object: 對象實例
- TestClass: 指定類
- mixed: 任意類型
- array: 數組
- TestClass[]: 指定類型數組
- resource: 文件資源
- void: 無
- null:
- callable: 回調函數
- function: 方法
- self/$this: 當前實例
@throws
拋出異常
@throws [類型] [描述]
@method
類注釋, 標明該類可以調用的方法, 可以令IDE自動提示等
/**
* @method string test(int num) 測試方法
*/
@param
標識參數信息, 類型可參考 @var
@param [類型] [名稱] [描述]
@property
類屬性, 指明可以直接訪問與修改的類屬性, 私有屬性需要通過 __get __set 魔術方法設置與訪問, 類型參考 @var
@property [類型] [名稱] [描述]
@property-read
類屬性, 指明只讀的類屬性, 私有屬性需要通過 __get 魔術方法訪問, 類型參考 @var
@property-write
類屬性, 指明只寫的類屬性, 私有屬性需要通過 __set 魔術方法設置, 類型參考 @var
@return
標識方法的返回值, 類型參考 @var
@return [類型] [描述]
@global
標明用到的全局變量
@global [類型] [名稱] [描述]
@ignore
標明生成文檔是忽略的值
@users
標明使用到了哪些值
/**
* @users Class::$num 使用此屬性計數
*/
有一些注釋沒有給出說明, 是因為個人不是常用, 當然還有一些注釋沒有總結到, 后面用到了再總結.