jsdoc进阶篇,用这些常用的类型标注来完善你的js代码吧

jsdoc的好处,可以看我上一篇文章:请抛弃行内注释,教你如何在typescript中更好的写注释

如何学习jsdoc可以看官网 JSDoc 中文文档

这里就不写一些简单的例子,直接上强度。

因为我们写jsdoc大多都是写函数的注释,所以我这里就以函数为例子,先了解基本的书写格式:

js 复制代码
/**
 * @标签名 { 类型 } 变量名 - 说明
 */

// 例子
/**
 * @param { strig } id - 这是请求的id
 */

一、如何标注一个对象类型?

定义一个getData的函数,它要接收一个params参数,这个参数是一个对象,里面有method,id,page属性。我们用ts可以很轻松的写出:

typescript 复制代码
interface TypeParams {
  method: 'POST' | 'GET'
  id: string
  page: number
}

function getData(params: TypeParams) {
  console.log(params.method)
}

但是如果用的是js,要怎么去写这个标注呢?我这里提供了3种方法

1.直接在类型里面写

js 复制代码
/**
 *
 * @param {{method:'POST'|'GET', id:string, page:number}} params 请求参数
 */
function getData(params) {
  console.log(params.method)
}

优点: 书写简洁

缺点:每个属性都缺少单独的类型说明

2.通过@param,以及对对象的扩展

js 复制代码
/**
 *
 * @param {object} params - 请求参数
 * @param {'POST'|'GET'} params.method - 请求类型
 * @param {string} params.id - 请求id
 * @param {number} params.page - 请求页数
 */
function getData(params) {
  console.log(params.method)
}

优点: 每个属性都有单独的说明

缺点:书写繁杂

3.通过@typedef和@property单独写一个类型,再引用

这种写法就很像ts的类型的写法

js 复制代码
/**
 *
 * @typedef {object} TypeParams - 请求参数类型
 * @property {'POST'|'GET'} params.method - 请求类型
 * @property {string} params.id - 请求id
 * @property {number} params.page - 请求页数
 */

/**
 *
 * @param {TypeParams} params - 请求参数
 */
function getData(params) {
  console.log(params.method)
}

/**
 *
 * @param {string} code - code
 * @param {TypeParams} params - 请求参数
 */
function List(code, params) {
  console.log(params.method)
}

优点: 可以类型复用

缺点:书写不够直观

总结

建议:一般来说,我推荐第二种写法。如果有类型复用的情况,并且是复用的次数很多,才考虑第三种写法。

扩展:函数默认参数值

用法

js 复制代码
/**
 * @标签名 { 类型 }[变量名=值] 变量名 - 说明
 */

// 例子
/**
 * @param { strig }[id='abc'] id - 这是请求的id
 */
js 复制代码
/**
 *
 * @param {object} params - 请求参数
 * @param {'POST'|'GET'}[params.method='GET'] params.method - 请求类型
 * @param {string} params.id - 请求id
 * @param {number} params.page - 请求页数
 * @param {string}[token='abc123456'] token - token
 */
function getData (params, token = 'abc123456') {
	console.log(params)
}

二、如何标注一个对象数组类型?

直接在类型后面加[],就这么简单

js 复制代码
/**
 *
 * @typedef {object} TypeParams - 请求参数
 * @property {'POST'|'GET'} params.method - 请求类型
 * @property {string} params.id - 请求id
 * @property {number} params.page - 请求页数
 */
 
/**
 *
 * @param {string[]} code - code
 * @param {TypeParams[]} params - 请求参数
 */
function List(code, params) {
  console.log(params)
}

三、如何标注一个枚举类型?

在ts中,枚举类型也是我用得最多的。但是换到了js,js没有枚举类型,只能用对象代替。但是如何写出好的注释,让它显示出对应的类型呢?

这里也提供了两种写法

1.通过@type标注

js 复制代码
/**
 * 映射状态的枚举
 * @readonly
 * @enum {1|2}
 */
const EnumState = {
  /**
   * 成功的值
   * @type {1}
   */
  PASS: 1,
  /**
   * 失败的值
   * @type {2}
   */
  ERROR: 2
}

2.用@default来标注

js 复制代码
/**
 * 映射状态的枚举
 * @readonly
 * @enum {1|2}
 */
const EnumState = {
  /**
   * 成功的值
   * @default 1
   */
  PASS: 1,
  /**
   * 失败的值
   * @type 2
   */
  ERROR: 2
}

总结

比较推荐第一种的写法

四、如何标注一个class类型?

实际上class我自己写得比较少,但是可能有人还是有需求,所以这里我也写一下

js 复制代码
/**
 * @class Person
 */
class Person {
  name
  #age
  /**
   * @static
   * @type {object} friend - 朋友
   * @property {string} friend.name - 名字
   * @property {number} friend.age - 年龄
   */
  static friend = { name: '', age: 22 }

  /**
   * @constructor
   * @param {string} name - name
   * @param {number} age - age
   */
  constructor(name, age) {
    /**
     * @property {string} name - 名字
     */
    this.name = name
    /**
     * @property {number} age - 年龄
     * @private
     */
    this.#age = age
  }
}

static遗留的问题

static friend那里标注得有点问题,不知道要怎么改,看有大神救一下吗。

五、如何学习写出更好的代码标注呢?

如何学习写出更好的代码标注呢?当然是点开node_modules,看一些这些著名的包是怎么写的啦

相关推荐
Mh8 小时前
我是如何设计品牌站组件库的?
前端·css·设计模式
程序员大阳8 小时前
副队长Vue3教程(2)--Vite 搭建 Vue 项目,认识目录结构
前端·javascript·vue.js·vite·创建项目·目录结构·项目结构
濮水大叔9 小时前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js
SoaringHeart9 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
Flynt11 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑11 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星11 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson11 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
其实防守也摸鱼12 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊12 小时前
CNC计算机数控加工模拟器
前端