简言

JSDoc 提供了向 JavaScript 代码库添加类型的功能，并在注释中使用适当的约定，这样不同的 IDE（如 Visual Studio Code）可以识别定义的类型，显示它们，并通过自动完成使编码更容易。定义放在/** */注释中。

举一个栗子

@typedef可以使用和标签定义自定义类型@property。每个属性都有一个类型，如果属性是可选的，则其名称放在方括号中，并且可以在属性名称之后包含描述。全局类型应该在*.jsdoc.js文件中定义，以便在不导入的情况下在多个文件中使用。*代表任何类型。

/** 
* @typedef {object} CollectionItem 
* @property {string} [collectionName] - 集合名称是可选的字符串字段
* @property {boolean} isRevealed - 显示状态
* @property {number} floorPrice - 底价
* @property { ?string} username - 用户名是一个可为空的字段
* @property {Array.<number>} prices - 价格数组
* @property {Array.<string>} [buyers] - 可选的买家数组
* @property {Array.<Object< string, *>>} data - 一些数据
*/

类是自动识别的，因此可以省略标签@class。@constructor

/** 
* 封装list请求
*/ 
class  getData { 
  /** 
   * 默认BaseURL
   * @param {string} url - API URL 
   */ 
  constructor (url) { 
    this.url = url; 
  } 
  // ...
 }

以描述开头的注释可以省略@description标签。@param函数参数和函数返回类型可以用和标签定义@returns。可以使用|运算符处理多个返回类型。代码库的弃用部分可以用@deprecated标签进行注释。

/** 
* 获取价格列表
* @private
 * @param { Array.<number> } prices - prices array 

* @returns { string |undefined } */ 
const  getPricesList = ( prices ) => { 
  if (prices.length > 0 ) return prices.join(',');

/** 
* 从 API 获取数据
* @deprecated 
* @returns {Promise<CollectionItem>} 
*/ 
const getData = async () => { 
  // ... 
};

变量类型可以用标签记录@type，常量可以使用@const标签。

/** 
* 请求计数器
* @type {number} 
*/ 
let counter;

/** 
* 以毫秒为单位的 HTTP 超时
* @const {number} 
*/ 
const HTTP_TIMEOUT_MS = 3000;

@enum枚举可以用和标签记录@readonly。

/** 
* xxx状态
* @readonly
 * @enum {string} 
*/ 
const  state = { 
  STARTED: 'STARTED' , 
  IN_PROGRESS: 'IN_PROGRESS' , 
  FINISHED: 'FINISHED' , 
};

文档验证

Linter 可以验证文档。添加以下包并更新 linter 配置文件。

npm i -D eslint-plugin-jsdoc

// .eslintrc.js
module.exports = { 
  extends: [ 'plugin:jsdoc/recommended' ], 
};

运行 linter，如果需要改进某些地方，它会显示警告。

生成文档概述

运行以下命令以递归生成带有文档概述的 HTML 文件，包括 README.md 和 package.json 内容。标有@private标签的符号将被跳过。

npx jsdoc src -r --destination docs --readme ./README .md  --package ./package .json

根据项目的需要，此命令可以包含在 CI/CD 管道中。

总结

看到这儿基本就都会用了，都明白怎么回事了。感谢大家(大哥)的观看！成功浪费大家 5 分钟。

番外篇

怕打不过多拿几把就是开了？