巧用jsdoc为vue项目生成漂亮文档

2023-12-09 04:47:59

前端项目的文档是一个很重要的部分，一个好的文档能够快速帮助我们了解项目的逻辑、使用方法等内容。

jsdoc是一个前端自动生成文档所常用的工具。我们只要按照jsdoc的语法来书写注释就能顺利的生成一片很漂亮的文档。

只是jsdoc针对的是js文件，对于.vue文件似乎就有些无能为力了。不过既然vue这么人气，相信一定也会有相应的工具。

在找了一圈之后，果然找到了一位前辈写的jsdoc-vue，只需要在命令行输入：

npm install jsdoc-vue

之后在项目根目录创建一个jsdoc.json配置文件。当然了，你也可以使用我提供的这个：

{
  "plugins": [
    "plugins/jsdoc-vue"
  ],
  "opts": {
    "template": "html",
    "destination": "dist-doc",
    "recurse": true
  },
  "source": {
    "include": [
      "src"
    ],
    "includePattern": "\\.js{
  "plugins": [
    "plugins/jsdoc-vue"
  ],
  "opts": {
    "template": "html",
    "destination": "dist-doc",
    "recurse": true
  },
  "source": {
    "include": [
      "src"
    ],
    "includePattern": "\\.js$",
    "excludePattern": "(node_modules/|bower_components/)"
  }
}
quot;,
    "excludePattern": "(node_modules/|bower_components/)"
  }
}

然后在命令行输入：

jsdoc -c jsdoc.json

就会自动帮你把项目的文档生成到dist-doc目录里了。

稍等片刻，这时可以在dist-doc目录下看到了生成的API文档。点击index.html文件可以查看。

当然了，不仅仅可以生成html格式的，还有node_module格式和json格式的。

如果你想查看node_module格式的文档，可以运行：

jsdoc --module -c jsdoc.json

这样就会生成相应的node_module格式的文档。

如果你想查看json格式的文档，可以运行：

jsdoc --json -c jsdoc.json

这样就会生成相应的json格式的文档。

那么这个时候可能你会有这样的疑问：

我的vue项目不可能只有一个src目录吧，我还有test、dist、docs等目录，这些目录不要生成文档吗？

不用担心，你可以通过source配置里include配置项来指定需要生成文档的目录：

{
  "source": {
    "include": [
      "src",
      "test",
      "docs"
    ],
    "includePattern": "\\.js$",
    "excludePattern": "(node_modules/|bower_components/)"
  }
}

这样当你执行jsdoc命令时就会把src、test、docs这三个目录下的js文件生成文档了。