整理一下PHP的註釋標記

語言: CN / TW / HK

什麼是註釋標記

我們在平常寫代碼或看別人寫的代碼時, 在方法的説明註釋中經常會有這樣的註釋:

/**
 * @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 <[email protected]>
 * hujing: 作者名
 * [email protected]: 郵箱
 */

@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 使用此屬性計數
 */

有一些註釋沒有給出説明, 是因為個人不是常用, 當然還有一些註釋沒有總結到, 後面用到了再總結.

以上內容希望幫助到大家,很多PHPer在進階的時候總會遇到一些問題和瓶頸,業務代碼寫多了沒有方向感,更多PHP大廠PDF面試文檔,PHP進階架構視頻資料,PHP精彩好文免費獲取可以關注公眾號:PHP開源社區,或者訪問:

2021金三銀四大廠面試真題集錦,必看!

四年精華PHP技術文章整理合集——PHP框架篇

四年精華PHP技術文合集——微服務架構篇

四年精華PHP技術文合集——分佈式架構篇

四年精華PHP技術文合集——高併發場景篇

四年精華PHP技術文章整理合集——數據庫篇