@use JSDoc

AMD 模組

概觀

JSDoc 3 可以用來記載使用 非同步模組定義 (AMD) API 的模組，此 API 由 RequireJS 等函式庫實作。此頁面說明如何根據模組使用的編碼慣例，為 JSDoc 記錄 AMD 模組。

如果您要記錄 CommonJS 或 Node.js 模組，請參閱 CommonJS 模組 以取得說明。

模組識別碼

當您記錄 AMD 模組時，您將使用 @exports 標籤 或 @module 標籤 來記錄傳遞給 require() 函式的識別碼。例如，如果使用者透過呼叫 require('my/shirt', /* callback */) 來載入模組，您將撰寫包含 @exports my/shirt 或 @module my/shirt 標籤的 JSDoc 註解。以下範例可以幫助您決定使用哪一個標籤。

如果您在沒有值的情況下使用 @exports 或 @module 標籤，JSDoc 將會嘗試根據檔案路徑猜測正確的模組識別碼。

當您使用 JSDoc 名稱路徑 從另一個 JSDoc 註解參照模組時，您必須加上 module: 前綴。例如，如果您希望 my/pants 模組的說明文件連結到 my/shirt 模組，您可以使用 @see 標籤 來記錄 my/pants 如下

/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

類似地，模組中每個成員的名稱路徑將從 module: 開始，後接模組名稱。例如，如果您的 my/pants 模組匯出 Jeans 建構函式，而 Jeans 有名為 hem 的實例方法，則實例方法的長名稱為 module:my/pants.Jeans#hem。

傳回物件文字的函式

如果您將 AMD 模組定義為傳回物件文字的函式，請使用 @exports 標籤 來記錄模組名稱。JSDoc 將自動偵測物件的屬性是否為模組的成員。

傳回物件文字的函式
define('my/shirt', function() {
   /**
    * A module representing a shirt.
    * @exports my/shirt
    */
    var shirt = {
        /** The module's `color` property. */
        color: 'black',

        /**
         * Create a new Turtleneck.
         * @class
         * @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
         */
        Turtleneck: function(size) {
            /** The class's `size` property. */
            this.size = size;
        }
    };

    return shirt;
});

傳回另一個函式的函式

如果您將模組定義為匯出另一個函式的函式，例如建構函式，您可以使用具有 @module 標籤 的獨立註解來記錄模組。然後，您可以使用 @alias 標籤 告訴 JSDoc 函式使用與模組相同長名稱。

傳回建構函式的函式
/**
 * A module representing a jacket.
 * @module my/jacket
 */
define('my/jacket', function() {
    /**
     * Create a new jacket.
     * @class
     * @alias module:my/jacket
     */
    var Jacket = function() {
        // ...
    };

    /** Zip up the jacket. */
    Jacket.prototype.zip = function() {
        // ...
    };

    return Jacket;
});

在回傳陳述式中宣告的模組

如果您在函式的 return 陳述式中宣告模組物件，您可以使用帶有 @module 標籤 的獨立註解來記錄模組。然後，您可以新增 @alias 標籤 來告訴 JSDoc 模組物件與模組具有相同的長名稱。

在回傳陳述式中宣告的模組
/**
 * Module representing a shirt.
 * @module my/shirt
 */

define('my/shirt', function() {
    // Do setup work here.

    return /** @alias module:my/shirt */ {
        /** Color. */
        color: 'black',
        /** Size. */
        size: 'unisize'
    };
});

傳遞給函式的模組物件

如果模組物件傳遞給定義模組的函式，您可以透過將 @exports 標籤 新增到函式參數來記錄模組。此模式在 JSDoc 3.3.0 及後續版本中受支援。

傳遞給函式的模組物件
define('my/jacket', function(
    /**
     * Utility functions for jackets.
     * @exports my/jacket
     */
    module) {

    /**
     * Zip up a jacket.
     * @param {Jacket} jacket - The jacket to zip up.
     */
    module.zip = function(jacket) {
        // ...
    };
});

在一個檔案中定義多個模組

如果您在單一 JavaScript 檔案中定義多個 AMD 模組，請使用 @exports 標籤 來記錄每個模組物件。

在一個檔案中定義多個 AMD 模組
// one module
define('html/utils', function() {
    /**
     * Utility functions to ease working with DOM elements.
     * @exports html/utils
     */
    var utils = {
        /**
         * Get the value of a property on an element.
         * @param {HTMLElement} element - The element.
         * @param {string} propertyName - The name of the property.
         * @return {*} The value of the property.
         */
        getStyleProperty: function(element, propertyName) { }
    };

    /**
     * Determine if an element is in the document head.
     * @param {HTMLElement} element - The element.
     * @return {boolean} Set to `true` if the element is in the document head,
     * `false` otherwise.
     */
    utils.isInHead = function(element) { }

    return utils;
    }
);

// another module
define('tag', function() {
    /** @exports tag */
    var tag = {
        /**
         * Create a new Tag.
         * @class
         * @param {string} tagName - The name of the tag.
         */
        Tag: function(tagName) {
            // ...
        }
    };

    return tag;
});