jsdoc教程

使用目的：开发过程中通过注释的方式 生成api文档 免去使用第三方mock接口的麻烦增加工作量

详情参考jsdoc官方网站 (opens new window)

安装

cnpm i jsdoc -g(-D)

配合插件

cnpm i vue-template-compiler -D

配置文件

{
  "plugins": ["node_modules/jsdoc-vue"],
  "source": {
    "includePattern": ".+\\.(vue|js)$" // 让其支持.vue文件的识别
  }
}

生成api文档

jsdoc -c config.json ./example

例子

js

/**
 * @name just test
 * @module filters/funny
 * @param  {string} value - input value
 * @return {string} original value
 */
export default function funny(value) {
  return value;
}

vue

<template>
  <label>
    <input :disabled="disabled" type="text" v-model="checkbox">
    <slot><slot>
  </label>
</template>

<script>
  /**
   * A simple checkbox component.
   * @module components/basic/checkbox
   * @param {number} [disabled=false] - Disabled component
   * @param {string[]} model - Required, need two way
   */
  export default {
    name: 'checkbox',
    props: {
      model: {
        type: Array,
        required: true,
        twoWay: true
      },
      disabled: Boolean
    }
  }
</script>

<style lang="css" scoped>
</style>

深度递归

举一个例子，假设你有以下文件结构：

myProject/
|- a.js
|- b.js
|- c.js
|- _private
|  |- a.js
|- lib/
   |- a.js
   |- ignore.js
   |- d.txt

你想获得myProject中所有的接口文档 需要配置config.json文件

配置

{
    "source": {
        "include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
        "exclude": ["myProject/lib/ignore.js"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

编译

jsdoc myProject/c.js -c /path/to/my/conf.json -r

从包含该myProject文件夹的文件 运行，JSDoc将为以下文件生成文档：

• myProject/a.js
• myProject/c.js
• myProject/lib/a.js

---

原因如下：

1. 鉴于source.include命令行给出的路径，JSDoc从这些文件开始：

• myProject/c.js （从命令行）
• myProject/a.js（从source.include）
• myProject/lib/a.js，myProject/lib/ignore.js，
• myProject/lib/d.txt（来自source.include和使用该 -r选项）

2. myProject/_private/a.js（从source.include）
3. JSDoc适用source.includePattern，留给我们所有的上述文件除 myProject/lib/d.txt，不结束.js，.jsdoc或.jsx。
4. JSDoc适用source.excludePattern，删除myProject/_private/a.js。 JSDoc适用source.exclude，删除myProject/lib/ignore.js。