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 名称路径 从另一个 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 一起使用