基于VS Code的JSDoc的使用指南

1. 引言

JSDoc是一个用于 JavaScript 的API文档生成器，可以将文档注释直接添加到源代码中，JSDoc 工具将扫描您的源代码并提供一些操作，例如，生成一个 API 文档

JSDoc官网：Use JSDoc: Index

JSDoc中文站点：JSDoc 入门 | JSDoc中文文档 | JSDoc中文网

GitHub站点：jsdoc/jsdoc: An API documentation generator for JavaScript. (github.com)

VS Code是前端常用的开发工具，其内置了JSDoc注解支持，可以参考：JavaScript Programming with Visual Studio Code

所以，使用JSDoc，可以实现：

美观的注释规范
编辑器的代码提示
API文档生成等

例如，使用VS Code打开Cesium源码：

可以看到Cesium中的注释是比较规范美观的，另外，鼠标悬浮在注释的变量或者函数上时，会有对应的类型提示

JSDoc主要是生成API 文档，但是与编辑器集成，将会带来代码编辑更好的体验

本文描述VS Code中JSDoc的使用指南

2. 快速使用

由于VS Code内置了JSDoc支持，在输入/**后就会触发语法提示：

随即就可键入注释内容：

保存文件之后，使用该函数或者鼠标悬浮这个函数之上时就会有相应提示：

安装JSDoc，就可以生成API文档

在当前目录下使用NPM安装JSDoc：

npm install jsdoc

运行JSDoc生成API文档：

npx jsdoc .\test.js

此时会在同目录下生成一个out文件，文件夹下有相关API的HTML文档：

JSDoc更为具体的命令参数和使用方法可以参考：JSDoc 入门 | JSDoc中文文档 | JSDoc中文网

综上，在VS Code中使用JSDoc，实现了：

美观的注释规范
编辑器的代码提示
API文档生成等

如果想生成Markdown文件，可以使用：jsdoc-to-markdown

使用方法也基本类似：

安装：

npm install jsdoc-to-markdown

运行：

npx jsdoc-to-markdown .\test.js

不过这个命令只是将数据输出在控制台终端（Terminal）中，要输入文件需要使用重定向字符或命令将数据输入文件：

npx jsdoc-to-markdown .\test.js > README.md

笔者注：使用Power Shell运行上述命令时产生的文件可能有乱码问题，可以使用CMD运行这个命令

API的Markdown文件生成完毕，更为具体的信息可以参考：jsdoc2md/jsdoc-to-markdown: Generate markdown documentation from jsdoc-annotated javascript (github.com)

3. 常用标签

这里以Cesium源码为例，列举一些常用的标签，完整详细的标签说明和命令使用请参考官方文档：Use JSDoc: Index

3.1 函数标签

Cesium源码core文件夹下的clone.js包含一个clone函数：

/**

 * Clones an object, returning a new object containing the same properties.

 *

 * @function

 *

 * @param {Object} object The object to clone.

 * @param {Boolean} [deep=false] If true, all properties will be deep cloned recursively.

 * @returns {Object} The cloned object.

 */

function clone(object, deep) {

  // ...

  return result;

}

其中，

第一句 Clones an object......properties.，是描述语句
@function，标记为一个函数
@param，标记函数参数的名称、类型和描述，格式为：{参数类型} 参数名参数描述
@returns，标记记录函数返回的值的名称、类型和描述

3.2 类标签

Cesium源码core文件夹下的Color.js包含一个Color类：

/**

 * A color, specified using red, green, blue, and alpha values,

 * which range from <code>0</code> (no intensity) to <code>1.0</code> (full intensity).

 * @param {Number} [red=1.0] The red component.

 * @param {Number} [green=1.0] The green component.

 * @param {Number} [blue=1.0] The blue component.

 * @param {Number} [alpha=1.0] The alpha component.

 *

 * @constructor

 * @alias Color

 *

 * @see Packable

 */

function Color(red, green, blue, alpha) {

  /**

   * The red component.

   * @type {Number}

   * @default 1.0

   */

  this.red = defaultValue(red, 1.0);

  // ...

}

其中，

@constructor，标记一个类的构造函数，API文档中为@constructs
@alias，标记成员的别名
@see，标记可以参考的另一个标识符的说明文档，或者一个外部资源
@type，标记一个类型表达式
@class，标记一个类

ES 2015 Class不需要使用诸如如 @class 和 @constructor 的标签来描述：

/**

 * 自定义Primitive

 *

 * @extends Cesium.Primitive

 */

class CustomPrimitive extends Cesium.Primitive {

  /**

   * 构造函数

   * @param {Object} options Primitive的参数

   */

  constructor(options) {

    super(options)

    const modelCenter = Cesium.Cartesian3.fromDegrees(121.474509, 31.233368, 0)

    const modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(modelCenter)

    this._modelMatrix = modelMatrix

  }

}

其中，

JSDoc 通过分析代码会自动识别类和它们的构造函数
@extends，指明标识符继承自哪个父类，同@augments
通常还有@example，提供代码标识的示例

3.3 常量标签

Cesium源码core文件夹下的Mtah.js包含很多常量：

/**

 * Math functions.

 *

 * @exports CesiumMath

 * @alias Math

 */

const CesiumMath = {};

/**

 * 0.1

 * @type {Number}

 * @constant

 */

CesiumMath.EPSILON1 = 0.1;

// ...

其中，

@constant，标记为常量

3.4 模块标签

常见的有，

@namespace，标记命名空间
@exports，标记导出内容
@module，标记一个模块

3.5 变量标签

常见的有，

@default，标记默认值
@enum，标记为枚举类型
@global，标记为全局变量
@kind，标记类型（例如，常量、函数等，不同于@class）
@readonly，标记为只读

4. 参考资料

[1] Use JSDoc: Index

[2] JSDoc 入门 | JSDoc中文文档 | JSDoc中文网

[3] 使用 jsDoc 提升我们的开发效率 - 知乎 (zhihu.com)

[4] JavaScript Programming with Visual Studio Code