jsdoc（文档注释）

介绍：JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。

说明：这里介绍的是把注释以一种类型文档的显示 做标注，不是普通的做个 文本描述。所以 JSDoc 的功能 和 typescript 的 类型描述文件的功能差不多。

参考：https://juejin.cn/post/7112831769736380430

一、常规：

• 可选参数：
  1. @param {type} [p] 可选参数
  2. @param {type=} p 可选参数

  /**
   * demo
   * @param {string} a
   * @param {string} [b] 
   * @param {boolean=} c
   */
  function foo(a, b, c) {}

• 参数默认值：
  1. @param {type} [p=defaultValue] 参数默认值

  /**  
   * demo * @param {string} a  
   * @param {string} b  
   * @param {boolean} [c=false]  
   */  
  function foo(a, b, c) {}

   

二、复杂的类型 注解：

• 数组结构:
  当参数为数组时可以做到对其每个元素进行详细描述，格式如下

  /**
   * 数组参数：
   * @param {array} arr 参数描述
   * @param {string} arr[0] 参数描述
   * @param {number} [arr[1]=undefined] 参数描述
   */

• 对象结构：

  /**
   * demo
   * @param {{name: string, age: number}} a
   * @returns {number}
   */
  function foo(a) {
    return 2;
  }

  上面的这种写法，会让维护者不解其中的意思。一时不知道name和age是什么意思。可以采用另一种描述 Object 中各项的描述，如下【推荐】

  /**
   * demo
   * @param {Object} a
   * @param {string} a.name 回复人的名字
   * @param {number} a.age 回复人的年龄
   * @returns {number}
   */
  function foo(a) {
    return 2;
  }

  如果 a 是已知对象

三、自定义类型：

有些时候我们可能需要使用复用一些结构体，可以使用 JSDoc 封装，如下

/**
 * 包含姓名和年龄的对象
 * @typedef {Object} Person
 * @property {string} name - 姓名
 * @property {number} age - 年龄
 */
/**
 * @type {Person} person
 */
 const person = {
   name: 'steven',
   age: 21
}

说明：自定义类型 类似ts的接口，多个地方复用这个对象类型时。自定义类型就非常好用。

• 定义方法：定义类型用  @typedef 和 @property 组合 

  /**
   * @typedef {Object} Person
   * @property {string} name how the person is called
   * @property {number} age how many years the person lived
   */

  使用时，直接把定义的类型 当作原生的类型那样使用

  /**
   * @param {Person} p - Description of p
   */

• 对于值都是相同类型的对象：数组对象中用的应该比较多。

  /**
   * @param {Object.<string, number>} dict
   */

• 描述函数返回值结构：如果函数返回值是一个普通对象哪个

四、继承：使用  @augments 或 @extends

　　    文档上显示的 @augments，别名是 @extends。个人还是循环使用@extends 表示

/**
 * @typedef {Object} resUser
 * @property {string} name
 * @property {number} age
 * @extends {resBase}
 */

五、跨文件使用

// ./@types/index
/**
 * 包含姓名和年龄的对象
 * @typedef {Object} Person
 * @property {string} name - 姓名
 * @property {number} age - 年龄
 */
/**
 * @type {Person} Person
 */

// ./t.js
/**
 * @typedef {import('./@types/index').Person}
 */
/**
 * demo
 * @param {Person} a
 * @returns
 */
function foo(a) {
  return 2;
}

 

总结：

JSDoc 在复用这方面，就不如 typescript 好用了，说实话，如果你的项目都需要用到这种类型了，应该尽快考虑是否应该使用 typescript，JSDoc 的生态方面还是比不过 typescript 的，而且两者写法差距蛮大，一旦写得多了，调头比较难。

六、接口：

接口 API 的注释还是挺重要的，如果 JSDoc 能用在这上面还是挺方便的，其示例如下

/**
 * demo
 * @returns {Promise<{data:{name: string, age: number}}>}
 */
function foo() {
  return new Promise((resolve, reject) => {
    resolve({ data: { name: "steven", age: 21 } });
  });
}

 

 

总结：偶尔使用 JSDoc 写点简单的注释还行，但是复杂的项目和类型，JSDoc 和它的生态未必能够撑得住。