JSDoc简介

JSDoc是JavaScript的一种重要的注释规范，在 JavaScript 代码中提供额外的文本注释以描述函数、类、方法、变量等等。通过解析这些注释，JSDoc可以自动生成API文档，为团队合作和项目交接提供了重要的支持。

JSDoc的语法

JSDoc遵循一套特定的注释规则，可以分为标记(tag)和块(block)两类注释。

标记(tag)注释

标记注释是以 @ 符号打头的注释，用于描述函数、类、方法、变量等的元数据信息。

标记注释具有以下基本语法结构：

/**
 * @tag {type} name - description
 */

其中，@ 符号后面紧跟着标记名，该标记名表示要描述的元数据信息类型；type表示元数据信息的类型；name表示元数据信息的名称；description表示元数据信息的描述。

块(block)注释

块注释是用 /** 开头和 */ 结尾的注释，用于描述函数、类、方法、变量等的详细信息。块注释可以包含多个标记注释，还可以包含JSDoc支持的特定的Markdown结构。

JSDoc的示例

下面是一个函数的JSDoc示例：

/**
 * Calculates the sum of two numbers.
 * @param {number} a - the first number to be calculated.
 * @param {number} b - the second number to be calculated.
 * @returns {number} the sum of the two numbers.
 */
function sum(a, b) {
  return a + b;
}

上面的示例使用了 @param 和 @returns 标记注释来描述函数的参数和返回值。

JSDoc的生成工具

JSDoc用于生成HTML文档，需要通过JSDoc生成工具来完成。其中JSDoc标准的生成工具是jsdoc，可以通过npm进行安装。

下面是使用jsdoc工具生成API文档的示例：

$ npm install -g jsdoc
$ jsdoc index.js -d docs

上面的命令将会在项目的根目录下的docs目录中生成API文档。

总结

JSDoc是一个重要的注释规范，可以帮助开发人员更好地描述代码中的函数、类、方法、变量等元数据信息，同时也可以通过生成工具自动生成API文档，提高代码质量和文档可读性。