@use JSDoc

入門

JSDoc 3是JavaScript的API文檔生成器，類似於Javadoc或phpDocumentor。您直接將文檔註釋添加到您的源代碼中，與代碼本身一起。JSDoc工具將掃描您的源代碼並為您生成HTML文檔網站。

為您的代碼添加文檔註釋

JSDoc的目的是記錄你的JavaScript應用程序或庫的API。假設你將要記錄諸如modules, namespaces, classes, methods, method parameters等等。

JSDoc評論通常應該在代碼記錄之前立即放置。每條評論都必須以一個/序列開始，以便被JSDoc解析器識別。開頭的註釋/，/或超過3分將被忽略。這是一個允許您禁止評論塊解析的功能。

/** This is a description of the foo function. */
function foo() {
}

添加描述很簡單 – 只需在文檔註釋中輸入您想要的描述。

特殊的"JSDoc標籤"可用於提供更多信息。例如，如果函數是class的構造函數，則可以通過添加@constructor標籤來指明。

使用JSDoc標籤來描述你的代碼

/**
* Represents a book.
* @constructor
*/
function Book(title, author) {
}

更多標籤可用於添加更多信息。查看JSDoc完整標籤列表。

用標籤添加更多信息

/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}

Block Tags

@abstract (synonyms: @virtual)
該成員必須由繼承者實現（或覆蓋）。

@access
指定此成員的訪問級別（私有，包私有，公共或受保護）。

@alias
對待一個成員，就好像它有一個不同的名字。

@async
指出一個函數是異步的。

@augments (synonyms: @extends)
指示符號從父符號繼承並添加到父符號。

@author
識別項目的作者。

@borrows
該對象使用來自另一個對象的東西。

@callback
記錄回調函數。

@class (synonyms: @constructor)
此功能旨在用“新”關鍵字調用。

@classdesc
使用以下文字來描述整個班級。

@constant (synonyms: @const)
將對象記錄為常量。

@constructs
這個函數成員將是前一個類的構造函數。

@copyright
記錄一些版權信息。

@default (synonyms: @defaultvalue)
記錄默認值。

@deprecated
記錄這不再是首選的方式。

@description (synonyms: @desc)
描述一個符號。

@enum
記錄相關屬性的集合。

@event
記錄一個事件。

@example
提供一個如何使用記錄項目的例子。

@exports
識別由JavaScript模塊導出的成員。

@external (synonyms: @host)
標識外部類，名稱空間或模塊。

@file (synonyms: @fileoverview, @overview)
描述一個文件。

@fires (synonyms: @emits)
描述此方法可能觸發的事件。

@function (synonyms: @func, @method)
描述一個函數或方法。

@generator
指出一個函數是一個生成器函數。

@global
記錄一個全局對象。

@hideconstructor
指示不應顯示構造函數。

@ignore
從文檔中省略符號。

@implements
這個符號實現了一個接口。

@inheritdoc
指示符號應該繼承其父文檔。

@inner
記錄一個內部對象。

@instance
記錄一個實例成員。

@interface
這個符號是其他人可以實現的接口。

@kind
這是什麼樣的符號？

@lends
對象文字的文檔屬性就好像它們屬於具有給定名稱的符號一樣。

@license
確定適用於此代碼的許可證。

@listens
列出符號偵聽的事件。

@member (synonyms: @var)
記錄一個成員。

@memberof
此符號屬於父母符號。

@mixes
該對象混合來自另一個對象的所有成員。

@mixin
記錄mixin對象。

@module
記錄一個JavaScript模塊。

@name
記錄對象的名稱。

@namespace
記錄一個名字空間對象。

@override
指示符號覆蓋其父項。

@package
這個符號是為了封裝私有的。

@param (synonyms: @arg, @argument)
將參數記錄到一個函數中。

@private
此符號旨在保密。

@property (synonyms: @prop)
記錄對象的屬性。

@protected
這個符號是為了保護。

@public
這個標誌是為了公開。

@readonly
此符號旨在為只讀。

@requires
這個文件需要一個JavaScript模塊。

@returns (synonyms: @return)
記錄函數的返回值。

@see
有關更多信息，請參閱其他文檔。

@since
此功能何時添加？

@static
記錄一個靜態成員。

@summary
完整描述的縮寫版本。

@this
‘this’關鍵字在這裡指的是什麼？

@throws (synonyms: @exception)
描述可能引發的錯誤。

@todo
文檔任務要完成。

@tutorial
插入指向包含的教程文件的鏈接。

@type
記錄對象的類型。

@typedef
記錄一個自定義類型。

@variation
區分具有相同名稱的不同對象。

@version
記錄項目的版本號。

@yields (synonyms: @yield)
記錄由發電機功能產生的值。

Inline Tags

{@link} (synonyms: {@linkcode}, {@linkplain})
鏈接到文檔中的另一個項目。

{@tutorial}
鏈接到教程。