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
