> JSDoc在线手册 > ES 2015 Modules(模块)

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
}