最近领导让写详细的注释，于是我就用了jsdoc，我发现用这挺爽的，虽然没有ts哪种强制报错，但是可以在普通的vue，react项目中使用，而且跟ts的语法类型，用的多的话对ts的学习也有帮助。注释这东西你写的越详细，后面你排查问题，重构代码会更方便，而且还可以根据注释自动生成api文档。下面总结jsdoc常用的语法。

1.@param 函数参数注释

     * 选择图标
     * @param {('chatboxIconType'|'chatboxMobileIconType')=} [key='chatboxIconType']
     * @param {number} index
     */
    choseIcon(key = "chatboxIconType", index) {
      this.cssStyle[key] = index + 1;
    }

number是必传的，key是非必传

2.@typedef 自定义类型

我们知道ts中有type和interface自定义类型和接口，@typedef作用类型，语法如下

/**
 * 样式配置对象
 * @typedef {Object} CssStyle
 * @property {string=} onlineText 属性注释
 * @property {string=} onlineMobileText 属性注释
 * @property {string=} chatButtonSideMargin 属性注释
 * @property {string=} chatButtonMobileSideMargin 属性注释
 * @property {string=} chatButtonBottomMargin 属性注释
 * @property {string=} chatButtonMobileBottomMargin 属性注释
 * @property {('bottom-right'|'bottom-left'|'side-right'|'side-left'|'circle-right'|'circle-left')} chatButtonLocation 属性注释
 * @property {('circle-right'|'circle-left'|'levitate'|'bottom')} chatButtonMobileLocation 属性注释
 * @property {(1|2|3|4|5|6|7|8|9|10)} chatboxIconType 属性注释
 * @property {(1|2|3|4|5|6|7|8|9|10)} chatboxMobileIconType 属性注释
 * @property {0|1} [chatButtonType=0] 属性注释
 * @property {0|1} [chatButtonMobileType=0] 属性注释
 * @property {string} [webCustomIcon] 属性注释
 * @property {string} [mobileCustomIcon] 属性注释
 */

那么如何使用这个自定义类型呢，有两种使用方式

a.为对象设置 @type语法

首先在js,jsx,vue文件中引入

/** @typedef {import("./interface").CssStyle} CssStyle */

接着设置类型

/** @type {CssStyle} */
const cssStyle = {}

这时候使用cssStyle就有提示

b.作为一个函数的类型

/**
 * @param {CssStyle} 样式对象
 */
function test(cssStyle){
}

3.数组，对象，字符串，布尔，枚举

/**
 * 各种类型
 * @typedef {Object} Test
 * @property {string[]} 字符串数组
 * @property {Record<string, any>|Object} 对象
 * @property {string} 字符串
 * @property {boolean} 布尔
 * @property {'1'|'2'|'3'} 枚举
 */

4.@template 范型

/**
* @template T
* @param {T} data
* @returns {T}
*/
function test(param){
 return param
}

其他还有一些类型，具体可以看官方文档：www.jsdoc.com.cn/。里面还有把jsdoc直接转成api文档的方法。

总结

如果是老的项目例如jquery，想在开发的时候有类型提示，可以尝试jsdoc，虽然没ts用这爽，增加注释的工作量，但是在旧的项目中有助于协同开发，方便自己，也方便他人

如何在vscode中写js写代码有堪比写ts的体验？