Модули ES 2015

Оглавление

• Идентификаторы модулей
• Экспортируемые значения
• Связанные ссылки

JSDoc 3 позволяет документировать модули, которые следуют спецификации ECMAScript 2015. Модули ES 2015 поддерживаются в JSDoc 3.4.0 и более поздних версиях.

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

При документировании модуля ES 2015 вы будете использовать тег @module для документирования идентификатора модуля. Например, если пользователи загружают модуль, вызвав import * as myShirt from 'my/shirt', вы напишете комментарий JSDoc, содержащий тег @module my/shirt.

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

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

Экспортируемые значения

Следующий пример демонстрирует, как документировать различные типы экспортируемых значений в модуле ES 2015. В большинстве случаев вы можете просто добавить комментарий JSDoc к оператору export , который определяет экспортируемое значение. Если вы экспортируете значение под другим именем, вы можете документировать экспортируемое значение в его блоке export.

/** @module color/mixer */

/** The name of the module. */
export const name = 'mixer';

/** The most recent blended color. */
export var lastColor = null;

/**
 * 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.
 */
export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)
function rgbify(color) {}

export {
    /**
     * Get the red, green, and blue values of a color.
     * @function
     * @param {string} color - A color, in hexadecimal format.
     * @returns {Array.<number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

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

• Использование имен путей с JSDoc 3
• @module