代码文档是软件开发使用和维护的必备资料,有了文档，开发和维护以及协作的效率将变得大大提升。tips：如果对 JSDoc 已经熟悉，可以直接跳到实战演练环节。

什么是文档？软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。文档的类型包括软件需求文档，设计文档，测试文档，用户手册等。

其中的代码文档一般是在软件开发过程中由开发者写就的，而用户手册等非过程类文档是由专门的非技术类写作人员写就的。 文档能提高软件开发的效率，保证软件的质量，而且在软件的使用过程中有指导、帮助、解惑的作用，尤其在维护工作中，文档是不可或缺的资料。

因此建立文档很有必要，对于前端从业者，我们可能更加熟悉接口文档，那有没有想过为自己的项目添加代码文档呢？特别是针对 vue项目，在没有Composition API 的情况下，可能同一功能的逻辑散落在.vue 文件的各个部分，使协作和维护变得困难和效率低下，特别是在那些没有 TypeScript 以及 Vue3 加持下的项目。因此今天我们就说一下，如何为你的 Vue项目编写代码文档。

如何写代码文档？

针对 JavaScript 项目添加文档，目前当下比较流行的方法使用 JSDoc 生成文档，按照 JSDoc 的标注在源代码中添加注释，使用 JSDoc 就能自动生成对应的文档.针对 Vue 项目，JSDoc 是不认识.vue 单文件的，因此还需要使用一款基于 JSDoc 的插件——jsdoc-vue 来生成。下面，让我们先分别来认识这两个工具。

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

它的使用姿势大概就是这样去编写一个函数的文档：

/*** @description 渲染每一行的样式,阶段进行中高亮，反之则不高亮* @param { object } row 每一行的数据* @returns {string} ("ing-row"|"other-row"|"start-row")*/

rowClass( row ) {

// 没有结束的独立阶段置为高亮 if (row.preStageId?.length === 0 && row.statue === 0) {

return "start-row";

} else if (row.statue === 1) {

// 进行中的高亮 return "ing-row";

}

// 其他的灰色 return "other-row";

},

这样注释之后，该部分最后得的文档是这样

生成的文档能够相应的标注出你的参数类型以及释义，以及该函数功能说明，以及返回参数说明。总之，就是对应输出你注释的内容，更多详细用法请看官方文档。下面着重说下如何使用 JSDoc针对 Vue 项目的插件jsdoc-vue.jsdoc-vue使用姿势一览​github.com

A JSDoc plugin for listing props, data, computed data, and methods from *.vue files.

翻译过来就是一个可以将.vue 文件中 props，data，computed，methods 这几个属性列出来的 JSDoc插件。

该插件的也很简单，就只是提供了四个语法 - @vue-prop (对应props) - @vue-data (对应data) - @vue-computed (对应 computed) - @vue-event (对应组件监听事件)

使用示例

/*** @vue-prop {Number} initialCounter - Initial counter's value* @vue-prop {Number} [step=1] - Step* @vue-data {Number} counter - Current counter's value* @vue-computed {String} message* @vue-event {Number} increment - Emit counter's value after increment* @vue-event {Number} decrement - Emit counter's value after decrement*/

除了特定的前缀不一样，使用方法和语法都是一样的。在配置好之后(稍后会讲如何配置)，你可以这样在.vue 中编写 vue 组件的文档

/*** 顶部选择当前大赛的组件* @vue-data { Boolean } firstEnter - 是否首次进入系统的标志，以本地缓存为准* @vue-computed { Object } currentRace - 系统当前选择的大赛* @vue-watch { Object } raceList - 大赛列表改变时，重新选择当前大赛，以防当前大赛被删除时，当前组件数据未更新* @vue-event { Void } handleDefaultRace - 选择当前的大赛的默认逻辑* @vue-event { Number } isFirstEnter - 判断是否是首次进入的逻辑* @vue-event { Boolean } competitionChange - 当用户主动切换大赛时触发的具体逻辑* @vue-event { Void } handleCommand - 当用户主动切换大赛时触发的中转时间*/

对应的文档会生成如下样式：

tips：.vue中的方法只需要注释在方法顶部就可，会自动同步文档到 methods 这一栏去。

上面已经介绍了这两个工具的基本使用，下面让我们具体来操作一下吧。

实战演练安装依赖

# 安装jsdoc jsdoc-vue

npm install --save-dev jsdoc jsdoc-vuejs

# vue 版本需要和 vue-tempate-compiler 版本一致，不然会报错，重要！

# 如果你使用 vue 的版本 2.5.21，请安装 vue-template-compiler 对应版本

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

# jsdoc 默认生成的和网站样式很简单，这里我们下载一个网站的html 模版

npm i -D tui-jsdoc-template2.编写配置

下载安装完毕，因为使用了插件，所以需要去配置我们的配置文件，详情参考如何配置 JSDoc 的配置文件​jsdoc.app

在项目根目录下新建一个 vuedoc.config.json

{

"plugins": ["node_modules/jsdoc-vuejs"], // 配置插件

"source": {

"includePattern": "\\.(vue|js)$" // 需要编译的文件，正则只包含.vue 和.js 文件

},

"opts": {

"template": "node_modules/tui-jsdoc-template" // 我们生成网站使用的模版

},

"templates": { // logo配置

"logo": {

"url": "http://img.pinxianhs.com/logo/logo.png",

"width": "30px",

"height": "30px",

"link": "https://github.com/nhnent/tui.jsdoc-template"

},

"name": "全国大学生工业设计大赛后台管理系统代码说明文档", // 网站顶部名称

"footerText": "全国大学生工业设计大赛后台管理系统",

"useCollapsibles": true,

"tabNames": {

"api": "API",

"tutorials": "Examples"

},

// 修改默认样式

"default": {

"staticFiles": {

"include": ["src/"]

}

},

"css": ["styles/doc.css"]

}

}3.添加注释

在.vue 文档中添加注释

.vue 部分

.methods 部分

4.生成网站,然后运行命令

jsdoc ./src -c ./vuedoc.config.json -r./src 要编译的目录

-c后面接的是配置文件名

-r代表递归编译子目录，默认最大层级 10

更多配置查看 JSDoc 使用方法。

编译之后，项目根目录下会多一个 out 文件夹，如图所示

我们再安装一个 http-server，将这个文档项目跑起来，安装依赖

npm i --save-dev http-server

以out 文件夹为根目录，在 http-server 里面跑起这个应用，要做的就是在 npm scripts 里面添加两条

"scripts": {

"serve:doc": "http-server ./out -p 3001 -o" //自动在浏览器打开文档网站，端口 3001 "doc": "jsdoc ./src -c ./vuedoc.config.json -r && npm run serve:doc", // 编译并自动打开文档网站 }

然后我们运行 npm run doc就能打开我们的vue 文档网站了。

运行界面

网站页面

logo以及顶部应用名称都可以自己配置，在样式方面，也可以自己在配置文件中覆盖。 左侧针对 es6 语法的 export 导出的文件都会自动被归类到 modules，顶层函数划分到 global 里面去，若有相应 class 也会自动归类。

值得一提的是，可以在这里进行全局搜索,可以快速 debug 和熟悉项目。

另外也可以进行代码溯源。

点击图片红框位置，可以快速看到源码，是不是太方便了。 赶快 get 吧。