使用JSDoc生成漂亮的文档

原文地址：https://qdgithub.com/home/index/article/aid/248.html

1. 什么是JSDoc

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

2. JSDoc可以用来干什么

• 生成清晰文档： 通过为函数、方法和类添加 JSDoc 注释，可以自动生成结构化的代码文档，包括用途、参数、返回值等信息。
• 提供类型信息： JSDoc 注释可以包含类型信息，帮助开发人员更好地了解参数和返回值的数据类型。
• 示例代码演示： JSDoc 注释可以包含示例代码，演示如何正确地使用函数和方法。
• 类型安全和提示： 集成开发环境（IDE）可以根据 JSDoc 注释提供代码自动完成、参数提示和跳转到定义等功能。

3. 快速入门JSDoc

直接来一个项目应用的实例，简单说一下jsdoc的使用流程，并展示一下最终得到的js的api文档。

3.1 安装JSDoc

全局安装或者局部安装，我这里选择的是全局，jsdoc版本是4.0.2

npm install jsdoc -g

npm install jsdoc -save-dev

在下面使用命令的时候，可能会报taffydb模块找不到。npm i taffydb -D安装解决。

3.2 使用JSDoc进行代码注释

以现有项目微信小程序中的socket.io.js为例，代码如下

/**
 * WebSocketIO module.
 * @module utils/WebSocketIO
 */

import {
   
  HEADER,
  SERVER_DEBUG,
  PINGINTERVAL,
  WSS_SOCKET_URL,
  RE_CONNECT_LIMIT
} from '../config.js';



/** 
 * 全局socket链接类
 * @class WebSocketIO
 * @see module:utils/WebSocketIO
 */
export default class WebSocketIO {
   
  constructor(app) {
   
    // 连接状态 false：未连接，true：已连接
    this.connectStatus = false
    this.timer = null // 心跳
    this.watcherList = {
   } // 订阅者
    this.app = app // 方便在Chat内部操作app
    this.limit = 0 // 记录重连次数
    this.rectimer = null // 重连定时器
    this.lockReconnect = false // 锁定重连尝试开关
    this.reclimit = RE_CONNECT_LIMIT // 断线最多尝试重连次数
    this.debug = SERVER_DEBUG //debug
  }

  /**
   * socket发起链接，且绑定回调
   */
  connectSocket() {
   
    let that = this;
    this.SocketTask = wx.connectSocket({
   
      url: WSS_SOCKET_URL,
      header: HEADER,
      success: res => {
   
        that.debug && console.log(res);
      },
      fail: err => {
   
        that.debug && console.log(err);
      }
    });

    wx.onSocketO