用 Propdoc 记录你的 Vue.js 组件

每个开发者都想读好文档,每个开发者都想写好文档,实际上只有少数开发者可以这样做,让我们来看看一个非常简单的方法,既可以为您的 Vue.js 组件生成文档,也可以使用 propdoc来渲染它。

安装

像任何其他 Vue 插件一样安装 propdoc:通过 Yarn 或 NPM。

1# Yarn
2$ yarn add propdoc
3
4# NPM
5$ npm install propdoc --save

文件组件

propdoc的最大特点是能够在组件上写你的文档作为属性。这些只有在你使用propdoc来渲染文档时才会使用。否则他们没有效果。

 1[label MyButton.vue]
 2<template>
 3  <div class="my-button" :class="{
 4    flat: isFlat,
 5    raised: isRaised,
 6    primary: isPrimary
 7  }">
 8    <slot></slot>
 9  </div>
10</template>
11
12<script>
13
14export default {
15  name: "my-button",
16  introduction: "A basic example button.",
17  description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
18  token: `<my-button isFlat isPrimary>Button Text</my-button>`,
19
20  props: {
21    isFlat: {
22      type: Boolean,
23      default: false,
24      note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
25    },
26
27    isRaised: {
28      type: Boolean,
29      default: true,
30      note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
31    },
32
33    isPrimary: {
34      type: Boolean,
35      default: false,
36      note: 'Whether or not to use the primary coloring.'
37    }
38  }
39}
40
41</script>

除了通常的内置密钥,如名称和组件和附件所需的密钥,propdoc 还添加了一些:

note: 告诉你什么是 prop
introduction: 对组件的快速介绍
description: 对组件的详细描述. 支持 Markdown
token: 显示如何使用组件的代码。

提供文档

对您的组件的文档也非常方便,只需添加propDoc组件,并在组件支持器中传递您的文档组件。

 1[label DocumentationComponent.vue]
 2<template>
 3  <div>
 4    <!-- Render the documentation for MyButton -->
 5    <prop-doc :component="MyButton"></prop-doc>
 6  </div>
 7</template>
 8
 9<script>
10import propDoc from 'propdoc';
11import MyButton from './MyButton.vue';
12
13export default {
14  components: {
15    propDoc
16  },
17
18  data() {
19    return {
20      MyButton
21    }
22  }
23}
24</script>