PHP注释标记整理
什么是注釋標記
我們在平常寫代碼或看別人寫的代碼時, 在方法的說明注釋中經常會有這樣的注釋:
/*** @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 使用此屬性計數*/有一些注釋沒有給出說明, 是因為個人不是常用, 當然還有一些注釋沒有總結到, 后面用到了再總結.
總結
- 上一篇： c语言 数组、字符串的形参格式_华中师范
- 下一篇： mysql 元数据获取_[MySQL]