@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;
});