添加AMD Modules

概述

JSDoc3 可以使用异步模块定义（AMD）API记录模块，这是由库实现的，如RequireJS。本页面说明根据您的模块使用的编码约定，如何使用JSDoc记录AMD模块。

如果你记录CommonJS或 Node.js的模块，见CommonJS 模块的说明。

模块标识符

当您记录一个AMD模块时，你要使用 [@exports 标签][exorts-tag]或@module 标签 来记录真实传递给require()函数的标识符。例如，如果用户通过调用require('my/shirt', /* callback */)来加载该模块，你会写一个包含@exports my/shirt 或 @module my/shirt标签的JSDoc注释。下面的例子可以帮助你决定使用哪些标签。

如果你使用不带值的@exports 或 @module 标签，JSDoc会基于文件路径尝试猜测正确的模块标识符。

当您使用 JSDoc namepath(名称路径)从另一个JSDoc注释中引用一个模块，您必须添加前缀module:。例如，如果你想模块my/pants的文档连接到模块my/shirt，您可以使用@see 标签来描述my/pants，如下：

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

同样，模块中每个成员的namepath （名称路径）将以module: 开始，后面跟模块名字。例如，如果你的my/pants模块输出一个Jeans构造函数，并且Jeans有一个名为hem的实例方法，那么这个实例方法longname（长名称）是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该函数使用相同的longname（长名称）作为模块。

示例: 返回构造函数的函数

/**
 * 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语句中声明模块

如果你在一个函数的return语句中声明你的模块对象，你可以使用一个独立的带有@module 标签的注释来记录模块。然后，您可以使用一个@alias 标签告诉JSDoc该函数使用相同的longname（长名称）作为模块。

示例: 模块声明在return语句中

/**
 * 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 标签来记录模块。这种模式在JSDoc3.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 标签来记录每个模块对象。

示例: 在一个文件中定义多个模块

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