使用 JSDoc 为 JavaScript 添加类型

随着 TypeScript 的普及，类型的概念在 JavaScript 中越来越重要，通过类型约束我们可以充分发挥 IDE 的代码提示功能，而且可以在开发过程中发现可能出现的问题。

虽然有了 TypeScript 来进行类型约束，但是 JSDoc 的地位并不能被完全取代，JSDoc 仍然可以为类型添加描述。

比如下面这个函数，在没有添加 JSDoc 注释之前将鼠标 hover 到函数上之后是这样的

在添加JSDoc 注释之后将鼠标 hover 之后是这样的

这是在 TypeScript 中，如果是在 JavaScript 中就是下面这样

可以看到，在 JavaScript 文件中，通过 JSDoc 声明函数参数类型之后，IDE 也能知道函数的参数及返回值类型。

有了类型，IDE 就能根据类型来给出合适的代码提示，从而提高我们的工作效率，此外更好的注释有利于我们的后期维护。

JSDoc 必须要使用块级注释，而且必须是两个星号（/** */）才可以生效。

常用的标识如下

函数相关的操作在文章的开头已经说过了，这里补充几个函数注释中常用的标识。

/**
 * 字符串末尾拼接 '2'
 * @version 1.0.0
 * @example
 * func('1')
 * @param {string} param1 参数 1
 * @returns {string} params+'2'
 */
function func(param1) {
  return param1 + '2'
}

效果如下

声明弃用之后的效果如下

使用@typedef定义类型，然后就可以享受 IDE 的代码提示了，这种酸爽是 JavaScript 不配拥有的。

又或者定义一组联合类型

然后就是和面向对象编程中常用的一下标识

/**
 * 动物抽象类
 * @constructor
 */
function Animal() {
  /** @protected */
  this._live = true
}
 
/**
 * 需要覆写的方法
 * @abstract
 * @returns {boolean}
 */
Animal.prototype.canFlay = function () {
  throw new Error('must be implemented by subclass!'); 
}
 
/**
 * 鸟 继承自动物抽象类
 * @constructor
 * @augments Animal
 */
function Bird() {
  /** @private */
  this._name = 'sparrow'
}
Bird.prototype = new Animal()
 
/**
 * 覆写父类的方法, 是否能飞行
 * @returns {boolean}
 */
Bird.prototype.canFlay = function () {
  return true
}
 
/** 
 * @function drink
 * @memberof Bird
 * @static
 */
Bird.drink = function () {
  console.log('drink');
}

最后，可以使用命令行来生成静态的文档

$ npx jsdoc js-doc.js