手把手教你引入jsdoc

为了增强代码规范，及降低阅读成本，引入jsdoc，自动生成文档

使用jsdoc-vue

jsdoc对于.vue的文件无法支持，所以选用jsdoc-vue
生成模板的处理使用minami模板

项目引入步骤

第一种方法：

npm install jsdoc-vue minami --save-dev

如果项目中没有vue-template-compiler

npm install vue-template-compiler --save-dev

项目如果遇到报错关于taffydb

npm install taffydb --save-dev

第二种方法：
在package.json文件中 devDependencies添加依赖

    "jsdoc-vue": "^1.0.0",
    "minami": "^1.2.3",
    "taffydb": "^2.7.3",
    "vue-template-compiler": "^2.6.11"

然后执行

npm install

项目配置

在项目的根目录下添加jsdoc-vue.js文件

var compiler = require('vue-template-compiler');

exports.handlers = {
  // 利用 vue-template-compiler 编译 vue 模板
  beforeParse: function (e) {
    if (/\.vue$/.test(e.filename)) {
      var output = compiler.parseComponent(e.source);

      e.source = output.script ? output.script.content : '';
    }
  }
};

添加.jsdoc.conf.json文件

{
  "tags": {
    "allowUnknownTags": true,

    "dictionaries": [
      "jsdoc"
    ]
  },

  "recurseDepth": 10,
  "source": {
    "include": [
      "./src/utils",
      "./src/views"
    ],
    "includePattern": ".+\\.(vue)$",
    "excludePattern": "(^|\\/|\\\\)_"
  },

  "plugins": [
    "./jsdoc-vue"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": true,
    "useLongnameInNav": false,
    "showInheritedInNav": true
  },
  "opts": {

    "destination": "./docs",
    "encoding": "utf8",
    "private": true,
    "recurse": true,
    "template": "./node_modules/minami"
  }
}

注意： “include"中配置的是需要包含的目录，这里需要根据项目需要改成各自的路径。例如 “include”: [”./src"]

destination属性配置生成文档的目录，推荐使用当前配置项，在根目录下生成docs文件夹

.gitignore配置

添加docs
忽略该文件夹，避免提交

运行脚本

可直接运行

jsdoc -c .jsdoc.conf.json

推荐在package.json的scripts脚本中添加

"doc": "jsdoc -c .jsdoc.conf.json"

项目中可使用生成文档

npm run doc

在项目的根目录就会生成docs文件夹，用浏览器打开index.html即可