1024解放双手|技术文档系统生成

文档生成技术选型

1. 技术选型,可选方案对比

可选方案jsdocvuepress
官网[vuepress官网](
www.vuepress.cn/guide/using… )
githubjsdoc gitHubvuepress 相关网站
帮助文档jsdoc中文网文档vuepress中文网
优点自动生成文档,支持主题切换,根据项目生成界面漂亮,代码隔离,组件引用
缺点根据项目生成需要手动维护
示例腾讯IM文档Eggjs文档vue官方相关项目

 

2. jsdoc快速使用

JSDOC 是一个 API 文档生成器,你只需要在代码中添加特定格式的注释,它就可以从注释中为你生成 HTML 文档。

2.1 全局安装:

// 全局安装
npm install -g jsdoc

如果你更倾向项目内使用,你也可以选择:

2. 2 基本使用

使用 JSDOC 非常简单,先为 JavaScript 文件写好注释,然后用 JSDOC 去解析即可:

2.2.1 新建demo.js

//  demo.js

/**
* 功能:将时间戳格式化为指定格式的字符串
* @param {Number} milliSec - 要转换的时间,可以为秒、毫秒、微秒、或Date类型
* @param {String} [formatStr] - 目标格式字符串 可选 默认为:'yyyy-MM-dd hh:mm:ss'
* @returns {String} - 根据目标时间格式,将时间数值(或Date)转换成的时间字符串
*/
function formatTime(milliSec, formatStr = DEFAULT_FORMAT_STR) {
  // code
}

2.2.2 运行命令生成文档

jsdoc demo.js

2.2.3 效果展示

3 项目中使用,通过配置项生成文档

在项目根目录下添加 jsdoc.json,然后通过 -c 参数来指定:

// jsdoc.json

{
  "source": {
    "include": [ "src/" ],
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "node_modules/docdash",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": true
  }
}
jsdoc -c jsdoc.json

无论 JSDOC 是通过全局安装,还是局部安装,都建议使用 npm scripts 来调用它,即在 package.jsonscripts 中添加命令(这里命名成 build:doc,可以根据自己爱好定义其他名字):

{
  "scripts": {
    "build-doc": "jsdoc -c jsdoc.json"
  }
}

这样我们就可以通过 npm run build-doc 来生成文档了。

如果实现修改文件后自动生成文档,只需要用类似 nodemon 之类的工具,监听指定文件的变化,然后再自动执行 npm run build-doc 就好了!

4. jsdoc,添加vue支持

4.1 jsdoc默认不支持支持js文件,使用jsdoc插件

npm install --save-dev jsdoc jsdoc-vuejs

4.2 添加vue文件

<template>
  <div>Hello world!</div>
</template>

<script>
  /**
   * @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 | Number} message
   * @vue-event {Number} increment - Emit counter's value after increment
   * @vue-event {Number} decrement - Emit counter's value after decrement
   * @module 报价管理-模块-主动推送订单
   */
  export default {
    props: {
      initialCounter: {
        type: Number,
        required: true,
      },
      step: {
        type: Number,
        default: 1,
      },
    },
    data () {
      return {
        counter: 0,
      }
    },
    computed: {
      message() {
        return `Current value is ${this.counter}`;
      }
    },
    methods: {
      increment() {
        this.counter += 1;
        this.$emit('increment', this.counter);
      },
      decrement() {
        this.counter -= 1;
        this.$emit('decrement', this.counter);
      }
    }
  }
</script>

4.3 配置项修改,添加jsdoc-vuejs配置项

{
  "plugins": [
    "node_modules/jsdoc-vuejs"
  ],
  "source": {
    "include": [ "src/" ],
    "includePattern": "\\.(vue|js)$",
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "templates/default",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": true
  }
}

5. 配置文件说明(跳转门

JSDOC 的配置项非常多,最常用的是下面这些:

  • source 表示传递给 JSDOC 的文件
  • source.include 表示 JSDOC 需要扫描哪些文件
  • source.exclude 表示 JSDOC 需要排除哪些文件
  • opts 表示传递给 JSDOC 的选项
  • opts.template 生成文档的模板,默认是 templates/default
  • opts.encoding 读取文件的编码,默认是 utf8
  • opts.destination 生成文档的路径,默认是 ./out/
  • opts.recurse 运行时是否递归子目录
  • opts.verbose 运行时是否输出详细信息,默认是 false

6. 注释说明 跳转门

我们知道,JSDOC 的工作原理是通过分析 JavaScript 文件中的注释来生成 HTML 文档的。 但是,如果想 JSDOC 生成正确的结果,我们需要编写正确格式的注释才行。它接受如下格式的注释:

这是我们在 JavaScript 中常见的级块注释。 需要注意的是,JSDOC 的解析器要求注释必须以 /** 开头,如果是以 /*/*** 或多于三个星号的注释都会被忽略。

有了这种级块注释,我们就可以在里面根据需要编写文档了。JSDOC 为我们提供了非常丰富的标签,它的解析器会对这些标签进行额外处理。这些标签大概可以分成两类:级块标签和行内标签。

  • 级块标签:位于注释的最顶层。JSDOC 中绝大部分标签都是级块标签。
  • 行内标签:位于级块标签内的标签,如 @link@tutorial

下面介绍一些常见的级块标签:

  • @author 该类/方法的作者。
  • @class 表示这是一个类。
  • @function/@method 表示这是一个函数/方法(这是同义词)。
  • @private 表示该类/方法是私有的,JSDOC 不会为其生成文档。
  • @name 该类/方法的名字。
  • @description 该类/方法的描述。
  • @param 该类/方法的参数,可重复定义。
  • @return 该类/方法的返回类型。
  • @link 创建超链接,生成文档时可以为其链接到其他部分。
  • @example 创建例子。

命名路径 (Namepaths)

不知道你有没有发现,上面例子中是用 Application#initialize 来表示一个实例方法的。如果是静态方法,那应该怎么表示呢?JSDOC 有自己的解析规则:

  • Constructor.Method 表示静态方法
  • Constructor#Method 表示实例方法
  • Constructor~Method 表示内部方法

了解了这些之后,我们就可以用 JSDOC 为 JavaScript 代码编写文档了,快去试试吧!

6.1 js文件注释示例

/**
 * @class
 * @name Application
 * @description Base Class of Application.
 * @param {Element} canvas The canvas dom element.
 * @param {Object} options The options of Application. See {@link Option} for detail.
 * @return {Application}
 *
 * @example
 * // create your application
 * new Application(canvas, options);
 */
export default class Aplication {

  /**
   * @private
   * @function
   * @name Application#intialize
   * @param {number} y - The y value.
   * @description Initialize the application.
   */
  initialize() {

  }

  /**
   * @param {number} page - 页码
   * @description Initialize the application.
   */
  initialize() {

  }
}

7 参考资料

参考文档

原文链接:juejin.im

上一篇:让你30分钟快速掌握vue 3
下一篇:vue2.x的patch方法和客户端混合(上)

相关推荐

官方社区

扫码加入 JavaScript 社区