AMD 模块

概述

¥Overview

JSDoc 3 可以记录使用 异步模块定义 (AMD) API 的模块，该模块由 RequireJS 等库实现。本页介绍了如何根据模块使用的编码约定为 JSDoc 记录 AMD 模块。

¥JSDoc 3 makes it possible to document modules that use the Asynchronous Module Definition (AMD) API, which is implemented by libraries such as RequireJS. This page explains how to document an AMD module for JSDoc, based on the coding conventions that your module uses.

如果你正在记录 CommonJS 或 Node.js 模块，请参阅 CommonJS 模块 了解说明。

¥If you're documenting CommonJS or Node.js modules, see CommonJS Modules for instructions.

模块标识符

¥Module identifiers

当你记录 AMD 模块时，你将使用 @exports 标签 或 @module 标签 来记录传递给 require() 函数的标识符。例如，如果用户通过调用 require('my/shirt', /* callback */) 加载模块，你将编写包含标签 @exports my/shirt 或 @module my/shirt 的 JSDoc 注释。下面的示例可以帮助你决定使用哪些标签。

¥When you document an AMD module, you'll use an @exports tag or @module tag to document the identifier that's passed to the require() function. For example, if users load the module by calling require('my/shirt', /* callback */), you'll write a JSDoc comment that contains the tag @exports my/shirt or @module my/shirt. The examples below can help you decide which of these tags to use.

如果你使用不带值的 @exports 或 @module 标记，JSDoc 将尝试根据文件路径猜测正确的模块标识符。

¥If you use the @exports or @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

当你使用 JSDoc namepath 引用另一个 JSDoc 注释中的模块时，你必须添加前缀 module:。例如，如果你希望模块 my/pants 的文档链接到模块 my/shirt，则可以使用 @see 标签 来记录 my/pants，如下所示：

¥When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

/**

 * Pants module.

 * @module my/pants

 * @see module:my/shirt
 */

同样，模块每个成员的名称路径将以 module: 开头，后跟模块名称。例如，如果你的 my/pants 模块导出 Jeans 构造函数，并且 Jeans 有一个名为 hem 的实例方法，则该实例方法的长名称为 module:my/pants.Jeans#hem。

¥Similarly, the namepath for each member of the module will start with module:, followed by the module name. For example, if your my/pants module exports a Jeans constructor, and Jeans has an instance method named hem, the instance method's longname is module:my/pants.Jeans#hem.

返回对象字面量的函数

¥Function that returns an object literal

如果将 AMD 模块定义为返回对象字面量的函数，请使用 @exports 标签 来记录模块的名称。JSDoc 将自动检测对象的属性是否是模块的成员。

¥If you define your AMD module as a function that returns an object literal, use the @exports tag to document the module's name. JSDoc will automatically detect that the object's properties are members of the module.

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

返回另一个函数的函数

¥Function that returns another function

如果将模块定义为导出另一个函数（例如构造函数）的函数，则可以使用带有 @module 标签 的独立注释来记录该模块。然后，你可以使用 @alias 标签 告诉 JSDoc 该函数使用与模块相同的长名称。

¥If you define your module as a function that exports another function, such as a constructor, you can use a standalone comment with a @module tag to document the module. You can then use an @alias tag to tell JSDoc that the function uses the same longname as the module.

/**

 * 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 declared in a return statement

如果你在函数的 return 语句中声明模块对象，则可以使用带有 @module 标签 的独立注释来记录该模块。然后，你可以添加 @alias 标签 来告诉 JSDoc 该模块对象与模块具有相同的长名称。

¥If you declare your module object in a function's return statement, you can use a standalone comment with a @module tag to document the module. You can then add an @alias tag to tell JSDoc that the module object has the same longname as the module.

/**

 * 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'
    };
});

传递给函数的模块对象

¥Module object passed to a function

如果模块对象被传递到定义模块的函数中，你可以通过向函数参数添加 @exports 标签 来记录该模块。JSDoc 3.3.0 及更高版本支持此模式。

¥If the module object is passed into the function that defines your module, you can document the module by adding an @exports tag to the function parameter. This pattern is supported in JSDoc 3.3.0 and later.

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) {
        // ...
    };
});

一个文件中定义多个模块

¥Multiple modules defined in one file

如果你在单个 JavaScript 文件中定义多个 AMD 模块，请使用 @exports 标签 来记录每个模块对象。

¥If you define more than one AMD module in a single JavaScript file, use the @exports tag to document each module object.

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

Related links

• @exports
• @module
• 将名称路径与 JSDoc 一起使用