jsdoc 小记

jsdoc 是一个可以根据注释自动生成文档的前端包。这在写公共库的时候很有用。相关文档也比较全面，问题是有时按照文档的操作，我没能得到预期的结果。

ps: 不要用 jsdoc-babel 插件。转译后的代码注释与预期不一样。

类注释

根据文档的说法，jsdoc 3.4 之后的 class 不需要手动添加 @class 之类的注视了，但是，我没能得到预期结果（jsdoc@3.6.7）。为了能让 class 和下面的方法都标注出来，尝试了个把小时。所以这里记录一下，贴个样例。

/**
 * @class NIM
 * @extends IMBase
 * @param {object} config 配置
 * @param {string} config.appKey 网易云信帐号<meta charset="utf-8">
 * @param {string} [config.debug=true] 网易云信帐号
 * @param {boolean} [immediateLogin] 是否需要立即登录，默认 true
 * @description 网易云信 im
 * @example 
 * ```
 * const config = {
 *   appKey: ''
 * }
 * new NIM(config)
 *
 * ```
 */
class NIM extends IMBase {
  constructor(config, immediateLogin = true) {
    super(config)
    /**
     * @memberof NIM
     * @type {object}
     */
    this.instance = null
  }

  /**
   * @memberof NIM
   * @method login
   * 登录
   */
  login() {
  }
}

对于需要嵌套的参数，需要在本参数下方使用 xx.yy 的方式注释。比如上面的 config 子属性。

更换模板

jsdoc 默认的模板不太美观。所以有时需要更换模板。这里以 docstrap 为例。

安装：

npm install ink-docstrap

然后修改文档生成脚本：

"scripts": {
  "build": "babel src --out-dir lib",
  "docs": "jsdoc -c jsdoc.json -t ./node_modules/ink-docstrap/template"
}

在 jsdoc.json 里可以配置一下文档标题（templates 部分）：

{
  "plugins": ["node_modules/jsdoc-babel"],
  "source": {
    "include": ["src"],
    "exclude": [],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "opts": {
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true
  },
  "templates": {
    "systemName": "药联聊天前端文档",
    "cleverLinks": false,
    "monospaceLinks": false
  }
}

---

前端的每一步都是磕磕碰碰。我顺利过吗？