JsDoc 代码内的文档标记

Azil大约 2 分钟

JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描你的源代码并为您生成一个 HTML 文档网站（当然，即使你不进行生成，其也被大部分浏览器所识别和支持）。JSDoc 的目的是记录 JavaScript 应用程序或库的 API。假设你想要记录诸如模块、名称空间、类、方法、方法参数等内容。 JSDoc注释通常应该放在记录代码之前。为了被 JSDoc 解析器识别，每个注释必须以 /** 序列开头。以 /*、/*** 开头或超过3颗星的注释将被忽略。这个特性用于控制解析注释块的功能。

JSDoc是一种用于为JavaScript代码生成文档的工具。它基于标签（tag）的形式，通过注释来提取代码中的类型、描述、参数、返回值等信息，生成文档供其他人参考。

使用JSDoc可以提高代码可读性和可维护性，让代码更易于理解和使用。在阅读和使用第三方库时，可以通过查看JSDoc生成的文档来了解函数和方法的使用方式、参数、返回值等信息。

常用标记语法

完整的标记请查看文档

@param 用于描述函数或方法的参数类型和含义
@returns 用于描述函数或方法的返回值类型和含义
@author 作者
@throws 抛出异常
callback 回调函数

/**
 * 根据【键、值】获取数据翻译
 * @param {String} key 键
 * @param {String} value 数据值
 * @returns {String} 返回内容
 */
function myFunction(key, value) {
  return 'xxx';
}

可选参数

使用方括号 [] 来标记

/**
 * 函数说明
 * @param {string} name - 名称
 * @param {string} [type] - 类型（可选）
 * @returns {string} 字符串
 */
function myFunction(name, type) {
  // 函数实现
  return 'xxx';
}

可选参数（带默认值）

使用等号 = 来标记带默认值的参数

/**
 * 函数说明
 * @param {string=} name - 名称
 * @param {string=} [type='default'] - 类型（可选，默认为 'default'）
 * @returns {string} 字符串
 */
function myFunction(name='', type='default') {
  // 函数实现
  return 'xxx';
}

对象内参

使用 @param 标签指明 config 是一个对象，并且包含两个属性： name 和 age 。其中 name 是可选属性。

/**
 * 函数说明
 * @param {Object} config - 配置项
 * @param {string=} config.name - 名称
 * @param {number} config.age - 年龄
 */
function myFunction(config) {
  // 函数实现
}