每一位 JSer 都應當掌握的註釋標記

簡介

註釋標籤在代碼註釋中的做用很是大，可是可能不少同窗在日常開發中會忽略這些標籤的做用，因此我這邊特意整理一些經常使用的註釋標記，經過圖文展示形式，但願能幫助你能更好理解每一個註釋標籤的做用.

想必掌握這些註釋標籤以後，不光對您從此的本身代碼編寫，仍是閱讀優秀源碼，都會帶來必定幫助.

或許你離漂亮的代碼，就差一個標籤^_^

項目工程地址 : github.com/yinggaozhen…

Egg源碼中大量註釋標記

經常使用標籤

@abstract

@abstract : 被此標記標識的成員方法，必須在繼承成員的對象中實現。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

別名 : @virtual

概述

該成員（通常指父類的方法）必須在繼承的子類中實現（或重寫）。

語法

@abstract

標籤效果

@constructor

@constructor : 被constructor標記的方法會被視爲構造函數.

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

@class [<type> <name>]

別名

@class

標籤效果

@deprecated

@deprecated : 被此標記的函數或者成員方法表示下個版本將會被廢棄，告知適用方再也不推薦使用此方法.

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

@deprecated [<some text>]

描述

• 若是被標記的方法只是由於被其餘新方法代替而被廢棄，能夠結合@see來表示被代替的方法

標籤效果

廢棄標籤

搭配@see

@inheritdoc

@inheritdoc : 指明這個標識應繼承其父類的文檔。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

@inheritdoc

標籤效果

@member

@member : 能夠爲某個成員變量定義類型.能夠選擇性爲成員變量指定名稱。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

別名

@var

語法

@member [<type>] [<name>]

type類型

type基礎類型

類型	說明
string	字符串
Array or Type[]	數組
number	數字
Object	對象
Class	自定義的類名
Function	方法類型
null	-
*	任意類型

type格式

類型名	語法示例	描述
Symbol name	{boolean} {myNamespace.MyClass}	指定符號的名稱。 若是標識符已經被文檔化，JSDoc將建立一個連接到該標識符的文檔
Multiple types	{number|boolean} 表示數字或布爾	這意味着值多是幾種類型中的一種，並用|分隔類型的完整列表。
Arrays	{Array.string} or string[] 表示字符串數組	-
Objects	{name: string, age : number} or Object	-
Nullable type	一個數字或null {?number}	指明類型爲指定的類型，或者爲null。
Non-nullable type	一個數字，可是絕對不會是null {!number}	指明類型爲指定的類型，可是絕對不會是null。
Variable number of that type	此函數接受可變數量的數值參數。 @param {...number} num	表示該函數接受可變數量的參數，並指定一個類型的參數
Optional parameter	一個可選參數 @param {number} [foo] @param {number} [foo=1] 可選參數，默認值=1	指示參數是可選的。當使用JSDoc的語法表示可選參數時，你還能夠指明參數的默認值。

標籤效果

@param

@param : 標籤提供了對某個函數的參數的各項說明，包括參數名、參數數據類型、描述等。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

@param {type} {name} {desc}

概述

@param標籤要求您指定要描述參數的名稱。您還能夠包含參數的數據類型，使用大括號括起來，和參數的描述。

類型表達式能夠有如下幾種表達形式

• 標識符的namepath(例如，myNamespace.MyClass)
• 一個內置的javascript類型(如string, number)
• 以上兩種的組合

標籤效果

函數入參定義類型

函數的入參是一個對象，能夠定義入參對象屬性類型

@see

@see : 此標籤表示能夠參考另外一個標識符的說明文檔，或者一個外部資源。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

• @see <namepath>
• @see <url>

標籤效果

動圖演示內容

• 經過@see標記的{Foo#bar}，能夠進行跳轉到Foo類中的bar成員屬性中
• 經過點擊@see標記的外部連接www.baidu.com，可跳轉到瀏覽器中查看

@throws

@throws : 說明可能會被拋出什麼樣的錯誤。

詳細代碼演示 : github.com/yinggaozhen…

此標籤推薦使用PhpStorm/WebStorm進行閱讀,能夠能直觀體現標籤的做用

語法

• @throws free-form description
• @throws {<type>}
• @throws {<type>} free-form description

概述

@throws標籤可讓你描述函數可能會拋出的錯誤。一個註釋塊中您能夠包含多個@throws標籤。

Example

/** * @description 拋出指定錯誤類型的錯誤 * @throws {SQLException} */
function tagThrows1() {
}

/** * @throws SQL Execute failed */
function tagThrows2() {
}

/** * @throws {SQLException} SQL Execute failed. */
function tagThrows3() {
}
複製代碼

最後

文章篇幅有限，這裏列舉了一部分標籤，更多標籤能夠經過如下工程地址

項目工程地址 : github.com/yinggaozhen…

標籤會不按期持續更新，歡迎各位star & fork

您的支持是我更新的最大動力~~