什么是注釋標(biāo)記

我們?cè)谄匠懘a或看別人寫的代碼時(shí), 在方法的說(shuō)明注釋中經(jīng)常會(huì)有這樣的注釋:

/*** @param $num* @return array*/

上面的*@param* @return 就是注釋標(biāo)記

注釋標(biāo)記用于生成文檔, param指明需要接收的參數(shù), return指明返回值

在使用 phpDocumentor 等工具生成文檔時(shí), 會(huì)識(shí)別相關(guān)注釋, 而且IDE也會(huì)識(shí)別, 在編碼的過(guò)程中會(huì)給出提示.

PHP注釋標(biāo)記總結(jié)

• @api: 提供給第三方使用的接口
• @author: 標(biāo)明作者
• @param: 參數(shù)
• @return: 返回值
• @todo: 待辦
• @version: 版本號(hào)
• @inheritdoc: 文檔繼承
• @property: 類屬性
• @property-read: 只讀屬性
• @property-write: 只寫屬性
• @const: 常量
• @deprecated: 過(guò)期方法
• @example: 示例
• @final: 標(biāo)識(shí)類是終態(tài), 禁止派生
• @global: 指明引用的全局變量
• @static: 標(biāo)識(shí)類、方法、屬性是靜態(tài)的
• @ignore: 忽略
• @internal: 限內(nèi)部使用
• @license: 協(xié)議
• @link: 鏈接,引用文檔等
• @see: 與 link 類似, 可以訪問(wèn)內(nèi)部方法或類
• @method: 方法
• @package: 命名空間
• @since: 從指定版本開(kāi)始的變動(dòng)
• @throws: 拋出異常
• @uses: 使用
• @var: 變量
• @copyright: 版權(quán)聲明

@author

標(biāo)明作者

/** @author hujing <hu@163.com>* hujing: 作者名* hu@163.com: 郵箱*/

@copyright

版權(quán)聲明

@copyright [描述]

@deprecated

標(biāo)明方法是不建議使用的、已過(guò)期的或?qū)⒁獎(jiǎng)h除的

/** 語(yǔ)法: * @deprecated [版本號(hào)] [描述]* eg:* @see Class::test()* @deprecated 2.0 將被棄用,請(qǐng)使用test方法*/

@inheritdoc

會(huì)繼承父類文檔, 且子類出現(xiàn)沖突文檔時(shí)重寫父類文檔

@internal

標(biāo)識(shí)此類或方法僅限當(dāng)前文件使用

@description [描述]

@link

指明外部鏈接, 必須給出完整url

@link [url] [描述]

@see

此鏈接不光可以跳轉(zhuǎn)到外部鏈接, 還可以跳轉(zhuǎn)到內(nèi)部的指定方法等, 如: class::method

@see [url|內(nèi)部方法] [描述]

@var

定義數(shù)據(jù)的類型

@var [類型] [變量名] [描述]

/*** 可以指定變量的類型* @var array 名稱列表* 也可以指定變量名, 指定變量時(shí)數(shù)組或空* @var array|null $nameList 名稱列表*/

類型列表如下:

• string: 字符串
• int/integer: 數(shù)字
• boolean/bool: 布爾
• float/double: 浮點(diǎn)
• object: 對(duì)象實(shí)例
• TestClass: 指定類
• mixed: 任意類型
• array: 數(shù)組
• TestClass[]: 指定類型數(shù)組
• resource: 文件資源
• void: 無(wú)
• null:
• callable: 回調(diào)函數(shù)
• function: 方法
• self/$this: 當(dāng)前實(shí)例

@throws

拋出異常

@throws [類型] [描述]

@method

類注釋, 標(biāo)明該類可以調(diào)用的方法, 可以令I(lǐng)DE自動(dòng)提示等

/*** @method string test(int num) 測(cè)試方法*/

@param

標(biāo)識(shí)參數(shù)信息, 類型可參考 @var

@param [類型] [名稱] [描述]

@property

類屬性, 指明可以直接訪問(wèn)與修改的類屬性, 私有屬性需要通過(guò) __get __set 魔術(shù)方法設(shè)置與訪問(wèn), 類型參考 @var

@property [類型] [名稱] [描述]

@property-read

類屬性, 指明只讀的類屬性, 私有屬性需要通過(guò) __get 魔術(shù)方法訪問(wèn), 類型參考 @var

@property-write

類屬性, 指明只寫的類屬性, 私有屬性需要通過(guò) __set 魔術(shù)方法設(shè)置, 類型參考 @var

@return

標(biāo)識(shí)方法的返回值, 類型參考 @var

@return [類型] [描述]

@global

標(biāo)明用到的全局變量

@global [類型] [名稱] [描述]

@ignore

標(biāo)明生成文檔是忽略的值

@users

標(biāo)明使用到了哪些值

/*** @users Class::$num 使用此屬性計(jì)數(shù)*/

---

有一些注釋沒(méi)有給出說(shuō)明, 是因?yàn)閭€(gè)人不是常用, 當(dāng)然還有一些注釋沒(méi)有總結(jié)到, 后面用到了再總結(jié).

總結(jié)

以上是生活随笔為你收集整理的PHP注释标记整理的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。