ES 2015 Modules

JSDoc3 能够记录遵循ECMAScript 2015规范的模块。ES 2015 模块在JSDoc3.4.0及更高版本中支持。

Module identifiers（模块标识符）

当你描述一个 ES 2015 module（模块）时，您将使用@module 标签来描述模块的标识符。例如，如果用户通过调用import * as myShirt from 'my/shirt' 加载模块，你会写一个包含@module my/shirt标签的JSDoc注释。

如果使用@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。

Exported values （导出值）

下面的示例演示如何在ES 2015 模块中描述不同种类的导出值。在多数情况下，你可以简单地在export语句上添加一个JSDoc注释来定义导出值。如果要以其他名称导出一个值，您可以在其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 hexidecimal format.
 * @param {string} color2 - The second color, in hexidecimal 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 hexidecimal format.
     * @returns {Array.<number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}