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 namepath 引用另一个 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 模块中记录不同类型的导出值。在大多数情况下，你只需将 JSDoc 注释添加到定义导出值的 export 语句中即可。如果你要以其他名称导出值，则可以在其 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