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;
}

三、自定义类型：

有些时候我们可能需要使用复用一些结构体，可以使用 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 和它的生态未必能够撑得住。

 

posted @ 2024-07-22 14:31  吴飞ff  阅读(2)  评论(0)  编辑  收藏  举报