ES 2015 Modules
优质
小牛编辑
134浏览
2023-12-01
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 (NULL, 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 }