ES 2015 模块

JSDoc 3 可以对遵循 ECMAScript 2015 规范的模块进行文档编制。JSDoc 3.4.0 及更高版本支持 ES 2015 模块。

🌐 JSDoc 3 makes it possible to document modules that follow the ECMAScript 2015 specification. ES 2015 modules are supported in JSDoc 3.4.0 and later.

模块标识符

🌐 Module identifiers

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

🌐 When you document an ES 2015 module, you'll use a @module tag to document the identifier for the module. For example, if users load the module by calling import * as myShirt from 'my/shirt', you'll write a JSDoc comment that contains the tag @module my/shirt.

如果你使用 @module 标签而不提供值，JSDoc 将尝试根据文件路径猜测正确的模块标识符。

🌐 If you use the @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

当你使用 JSDoc 名称路径从另一个 JSDoc 注释引用一个模块时，你必须添加前缀 module:。例如，如果你希望模块 my/pants 的文档链接到模块 my/shirt，你可以使用 @see 标签来如下文档 my/pants：

🌐 When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

同样，每个模块成员的名称路径将以 module: 开头，后跟模块名称。例如，如果你的 my/pants 模块导出一个 Jeans 类，并且 Jeans 有一个名为 hem 的实例方法，那么该实例方法的长名称是 module:my/pants.Jeans#hem。

🌐 Similarly, the namepath for each member of the module will start with module:, followed by the module name. For example, if your my/pants module exports a Jeans class, and Jeans has an instance method named hem, the instance method's longname is module:my/pants.Jeans#hem.

导出值

🌐 Exported values

以下示例演示了如何在 ES 2015 模块中记录不同类型的导出值。在大多数情况下，你可以简单地在定义导出值的 export 语句上添加一个 JSDoc 注释。如果你以另一个名称导出一个值，你可以在其 export 块中记录该导出值。

🌐 The following example shows how to document different kinds of exported values in an ES 2015 module. In most cases, you can simply add a JSDoc comment to the export statement that defines the exported value. If you are exporting a value under another name, you can document the exported value within its export block.

记录模块导出的值

/** @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.&lt;number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

ES 2015 模块

模块标识符

导出值

Related links