Модули CommonJS

Оглавление

• Обзор
• Идентификаторы модулей
• Свойства объекта 'exports'
• Значения, присваиваемые локальным переменным
• Значения, присваиваемые 'module.exports'
  • Объектная запись, присвоенная 'module.exports'
  • Функция, присвоенная 'module.exports'
  • Строка, число или булево значение, присвоенные 'module.exports'
• Значения, присваиваемые 'module.exports' и локальным переменным
• Свойства, добавленные к 'this'
• Ссылки

Обзор

Чтобы помочь вам документировать модули CommonJS, JSDoc 3 понимает многие из конвенций, используемых в спецификации CommonJS (например, добавление свойств к объекту exports). Кроме того, JSDoc распознает конвенции модулей Node.js, которые расширяют стандарт CommonJS (например, присвоение значения module.exports). В зависимости от используемых вами правил кодирования, вам может потребоваться предоставить некоторые дополнительные теги, чтобы помочь JSDoc понять ваш код.

Эта страница объясняет, как документировать модули CommonJS и Node.js, использующие различные правила кодирования. Если вы документируете модули Asynchronous Module Definition (AMD) (также известные как модули RequireJS), см. AMD-модули.

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

В большинстве случаев ваш модуль CommonJS или Node.js должен включать автономный комментарий JSDoc, который содержит тег @module. Значение тега @module должно соответствовать идентификатору модуля, который передается функции require(). Например, если пользователи загружают модуль, вызывая require('my/shirt'), в вашем комментарии JSDoc будет содержаться тег @module my/shirt.

Если вы используете тег @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, полное имя метода экземпляра — module:my/pants.Jeans#hem.

Свойства объекта 'exports'

Проще всего документировать символы, которые напрямую присваиваются свойству объекта exports. JSDoc автоматически распознает, что эти символы экспортирует модуль.

В следующем примере модуль my/shirt экспортирует методы button и unbutton. JSDoc автоматически определит, что модуль экспортирует эти методы.

/**
 * Shirt module.
 * @module my/shirt
 */

/** Button the shirt. */
exports.button = function() {
    // ...
};

/** Unbutton the shirt. */
exports.unbutton = function() {
    // ...
};

Значения, присваиваемые локальным переменным

В некоторых случаях экспортируемый символ может быть присвоен локальной переменной до добавления его в объект exports. Например, если ваш модуль экспортирует метод wash, а сам модуль часто вызывает метод wash, вы можете написать модуль так:

/**
 * Shirt module.
 * @module my/shirt
 */

/** Wash the shirt. */
var wash = exports.wash = function() {
    // ...
};

В этом случае JSDoc не автоматически задокументирует wash как экспортируемый метод, потому что комментарий JSDoc находится непосредственно перед локальной переменной wash, а не перед exports.wash. Одним из решений является добавление тега @alias, который определяет правильное полное имя метода. В этом случае метод является статическим членом модуля my/shirt, поэтому правильное полное имя — module:my/shirt.wash:

/**
 * Shirt module.
 * @module my/shirt
 */

/**
 * Wash the shirt.
 * @alias module:my/shirt.wash
 */
var wash = exports.wash = function() {
    // ...
};

Другим решением является перемещение комментария JSDoc метода так, чтобы он находился непосредственно перед exports.wash. Это изменение позволяет JSDoc определить, что wash экспортируется модулем my/shirt:

/**
 * Shirt module.
 * @module my/shirt
 */

var wash =
/** Wash the shirt. */
exports.wash = function() {
    // ...
};

Значения, присваиваемые 'module.exports'

В модуле Node.js вы можете напрямую присвоить значение module.exports. Этот раздел объясняет, как документировать различные типы значений при их присвоении module.exports.

Объектная запись, присвоенная 'module.exports'

Если модуль присваивает объектную запись module.exports, JSDoc автоматически распознает, что модуль экспортирует только это значение. Кроме того, JSDoc автоматически задает правильное полное имя для каждого свойства:

/**
 * Color mixer.
 * @module color/mixer
 */

module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    },

    /**
     * Darken a color by the given percentage.
     * @param {string} color - The color, in hexadecimal format.
     * @param {number} percent - The percentage, ranging from 0 to 100.
     * @return {string} The darkened color.
     */
    darken: function(color, percent) {
        // ..
    }
};

Вы также можете использовать эту схему, если добавляете свойства к module.exports вне объектной записи:

/**
 * Color mixer.
 * @module color/mixer
 */

module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    }
};

/**
 * Darken a color by the given percentage.
 * @param {string} color - The color, in hexadecimal format.
 * @param {number} percent - The percentage, ranging from 0 to 100.
 * @return {string} The darkened color.
 */
module.exports.darken = function(color, percent) {
    // ..
};

Функция, присвоенная 'module.exports'

Если вы присваиваете функцию module.exports, JSDoc автоматически задаст правильное полное имя для функции:

/**
 * Color mixer.
 * @module color/mixer
 */

/**
 * Blend two colors together.
 * @param {string} color1 - The first color, in hexadecimal format.
 * @param {string} color2 - The second color, in hexadecimal format.
 * @return {string} The blended color.
 */
module.exports = function(color1, color2) {
    // ...
};

Такая же схема работает и для конструкторских функций:

/**
 * Color mixer.
 * @module color/mixer
 */

/** Create a color mixer. */
module.exports = function ColorMixer() {
    // ...
};

Строка, число или булево значение, присвоенные 'module.exports'

Для типов значений (строки, числа и булевы значения), присвоенных module.exports, вы должны документировать тип экспортированного значения, используя тег @type в том же комментарии JSDoc, что и тег @module:

/**
 * Module representing the word of the day.
 * @module wotd
 * @type {string}
 */

module.exports = 'perniciousness';

Значения, присваиваемые 'module.exports' и локальным переменным

Если ваш модуль экспортирует символы, которые не присваиваются напрямую module.exports, вы можете использовать тег @exports вместо тега @module. Тег @exports сообщает JSDoc, что символ представляет экспортированное значение модуля.

/**
 * Color mixer.
 * @exports color/mixer
 */
var mixer = module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    }
};

Свойства, добавленные к 'this'

Когда модуль добавляет свойство к своему объекту this, JSDoc 3 автоматически распознает, что новое свойство экспортировано модулем:

/**
 * Module for bookshelf-related utilities.
 * @module bookshelf
 */

/**
 * Create a new Book.
 * @class
 * @param {string} title - The title of the book.
 */
this.Book = function(title) {
    /** The title of the book. */
    this.title = title;
}

Ссылки

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