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

應果真發表於2019-06-24
JS

簡介

註釋標籤在程式碼註釋中的作用非常大，但是可能很多同學在平常開發中會忽略這些標籤的作用，所以我這邊特地整理一些常用的註釋標記，通過圖文展現形式，希望能幫助你能更好理解每個註釋標籤的作用.

想必掌握這些註釋標籤之後，不光對您今後的自己程式碼編寫，還是閱讀優秀原始碼，都會帶來一定幫助.

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

專案工程地址 : github.com/yinggaozhen…

Egg原始碼中大量註釋標記

Egg原始碼中註釋截圖

常用標籤

@abstract

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

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

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

別名 : @virtual

概述

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

語法

@abstract

標籤效果

demo.jpg

@constructor

@constructor : 被constructor標記的方法會被視為建構函式.

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

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

語法

@class [<type> <name>]

別名

@class

標籤效果

demo.jpg

@deprecated

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

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

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

語法

@deprecated [<some text>]

描述

  • 如果被標記的方法只是因為被其他新方法代替而被廢棄，可以結合@see來表示被代替的方法

標籤效果

廢棄標籤

demo1.jpg

搭配@see

demo2.jpg

@inheritdoc

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

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

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

語法

@inheritdoc

標籤效果

demo.jpg

@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的語法表示可選引數時，你還可以指明引數的預設值。

標籤效果

demo.jpg

@param

@param : 標籤提供了對某個函式的引數的各項說明，包括引數名、引數資料型別、描述等。

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

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

語法

@param {type} {name} {desc}

概述

@param標籤要求您指定要描述引數的名稱。您還可以包含引數的資料型別，使用大括號括起來，和引數的描述。

型別表示式可以有以下幾種表達形式

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

標籤效果

函式入參定義型別

demo.jpg

函式的入參是一個物件，可以定義入參物件屬性型別

demo.jpg

@see

@see : 此標籤表示可以參考另一個識別符號的說明文件，或者一個外部資源。

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

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

語法

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

標籤效果

動圖演示內容

  • 通過@see標記的{Foo#bar}，可以進行跳轉到Foo類中的bar成員屬性中
  • 通過點選@see標記的外部連結www.baidu.com，可跳轉到瀏覽器中檢視

demo.jpg

@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

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

相關文章