Модули AMD

Содержание

• Обзор
• Идентификаторы модулей
• Функция, возвращающая объект-литерал
• Функция, возвращающая другую функцию
• Модуль, объявленный в операторе return
• Объект модуля, переданный в функцию
• Несколько модулей, определённых в одном файле
• Связанные ссылки

Обзор

JSDoc 3 позволяет документировать модули, использующие API Asynchronous Module Definition (AMD), реализованный такими библиотеками, как RequireJS. На этой странице объясняется, как документировать модуль AMD для JSDoc, основываясь на соглашениях об именовании, используемых в вашем модуле.

Если вы документируете модули CommonJS или Node.js, см. Модули CommonJS для получения инструкций.

Идентификаторы модулей

При документировании модуля AMD вы будете использовать тег @exports или @module для документирования идентификатора, который передаётся в функцию require(). Например, если пользователи загружают модуль, вызывая require('my/shirt', /* callback */), вы напишете комментарий JSDoc, содержащий тег @exports my/shirt или @module my/shirt. Примеры ниже помогут вам определиться с выбором тега.

Если вы используете тег @exports или @module без значения, JSDoc попытается определить правильный идентификатор модуля на основе пути к файлу.

Когда вы используете JSDoc namepath для ссылки на модуль из другого комментария 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

Если вы объявляете объект модуля в операторе 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) {
        // ...
    };
});

Несколько модулей, определённых в одном файле

Если вы определяете более одного модуля AMD в одном файле JavaScript, используйте тег @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;
});

Связанные ссылки

• Использование namepath в JSDoc 3
• @exports
• @module