vuese介绍

介绍

• vuese是一个根据你的代码自动生成文档的工具
• git地址

---

安装

`yarn global add vuese`  

---

特性

• 识别vue中的name,props,evnets,slots,methods然后生成markdown文档
• 文档集合：生成一个文档服务
• 注释增强（@XXX）

---

用法

基础

vuese的命令非常简单，其提供了两种基础命令

• vuese gen 基于现有代码和设置生成代码
• vuese server启动服务来访问生成的网站

配置

vuese会读取根目录下的vuese.config.js或者.vueserc或者package.josn的vuese属性。
一下配置可以写在配置文件中也可以写在命令行中。

使用命令行

vuese gen --include="./src/*.vue

include

• Type: string string[]
• Default: [“/*.vue”]
  指定解析那些.vue文件，默认是解析当前目录下及子目录下的所有.vue文件。

exclude

• Type: string string[]
• Default: []
  与上面的配置相反，exclude指定哪些.vue文件不用被解析。node_modules/**/*.vue默认不解析。

outDir

• Type: string
• Default: website
  设置输出文档的目录

markdownDir

• Type: string
• Default: components
  设置markdown文档的输出目录，这个目录是依赖outDir设置的目录的。（如果你设置../doc它就会跑出文档）

genType

• Type: string
• Default: ‘’
  设置输出文档类型，可以是docute或者markdown，不设置的话会询问

title

• Type: string
• Default: ‘’
  设置输出文档的标题

如何编写文档

只要在写代码时添加一些注释就可以很方便的生成文档

props

在对应的props属性上方添加注释可作为描述，在内部写的注释则会作为type的补充，如果你只提供几个可选值则可以写在这里

props: {
  // The name of the form
  name: {
    // `'TOP'` / `'BOTTOM'`
    type: String,
    required: true,
    default: 'TOP'
  }
}

---

slots

在slot的上方添加注释会作为此slot的描述，在slot中添加注释则会成为此slot的默认值（你写的代码却不会成为默认值），而且如果你的代码中存在slot嵌套则你必须写两条注释来作为外层slot的默认值和内层slot的描述（奇怪的设定）

<!-- Form header -->
<slot name="header">
  <!-- `<th>title</th>` -->
  <!-- Custom form header -->
  <slot name="defaultHeader"></slot>
</slot>

---

events

vuese只会识别this.$emit() 来生成到文档中，这也很好理解，vue希望我们使用事件来完成父子组件通信，所以使用组件的人也只需要关注组件暴露出来的事件即可。
如果你的事件存在参数则你需要用@arg 来描述它如果你不描述的话则文档中不会存在这个参数

methods: {
  clear () {
    // Fire when the form is cleared
    // @arg The argument is a boolean value representing xxx
    this.$emit('onclear', true)
  }
}

---

methods

vuese并不会默认解析所有的方法，如果你希望methods出现在文档中你必须使用@vuese 来标记它，这个也很好理解，我们组件内的方法通常都是供自己使用，很少有需要暴露给用户的情况，所以我们需要手动来标记那些需要暴露的方法。

methods: {
  /**
   * @vuese
   * Used to manually clear the form
   * @arg The argument is a boolean value representing xxx
   */
  clear (bol) {
    // ...
  }
}

---

#前端/VUE