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.

If you’re documenting CommonJS or Node.js modules, see CommonJS 模块 for instructions.

模块标识符

When you document an AMD module, you’ll use an @exports or @module 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.

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

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 to document my/pants as follows:

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

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.

返回对象文字的函数

If you define your AMD module as a function that returns an object literal, use the @exports 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;
});

返回另一个函数的函数

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 to document the module. You can then use an @alias to tell JSDoc that the function uses the same longname as the module.

Function that returns a constructor

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

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

模块在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'
    };
});

传递给函数的模块对象

If the module object is passed into the function that defines your module, you can document the module by adding an @exports 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) {
        // ...
    };
});

在一个文件中定义多个模块

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

Multiple AMD modules defined in one file

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