整理一下PHP的註釋標記

語言: CN / TW / HK

時間 2021-07-20 13:02:28 程式設計師安安

什麼是註釋標記

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

/**
 * @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技術文章整理合集——資料庫篇

「其他文章」