すべての開発者は、優れたドキュメントを読みたいと思っています。 すべての開発者は、優れたドキュメントを書きたいと思っています。 実際に行う開発者はほとんどいません。 Vue.jsコンポーネントのドキュメントを生成し、propdocを使用してレンダリングする非常に簡単な方法を見てみましょう。

インストール

他のVueプラグインと同じようにpropdocをインストールします:YarnまたはNPMを介して。

# Yarn
$ yarn add propdoc

# NPM
$ npm install propdoc --save

コンポーネントの文書化

propdoc の最大の機能は、コンポーネントのプロパティとしてドキュメントを作成できることです。 これらは、propdocを使用してドキュメントをレンダリングする場合にのみ使用されます。 それ以外の場合は効果がありません。 驚いたのは、これまでになかったような天才的なアイデアです。

MyButton.vue
<template>
  <div class="my-button" :class="{
    flat: isFlat,
    raised: isRaised,
    primary: isPrimary
  }">
    <slot></slot>
  </div>
</template>

<script>

export default {
  name: "my-button",
  introduction: "A basic example button.",
  description: "A basic button with the ability to be flat, raised, or be a primary button. Nothing super special. (I stink at writing documentation.)",
  token: `<my-button isFlat isPrimary>Button Text</my-button>`,

  props: {
    isFlat: {
      type: Boolean,
      default: false,
      note: 'Whether or not to use the flat version of the button. (No gradient or outline.)'
    },

    isRaised: {
      type: Boolean,
      default: true,
      note: 'Whether or not to use the raised version of the button. (Has a drop shadow.)'
    },

    isPrimary: {
      type: Boolean,
      default: false,
      note: 'Whether or not to use the primary coloring.'
    }
  }
}

</script>

コンポーネントと小道具にnamerequiredなどの通常の組み込みキーに加えて、propdocはさらにいくつか追加します。

  • note :小道具が何をするかを伝えます。
  • はじめに:コンポーネントの簡単な紹介。
  • description :コンポーネントの詳細な説明。 マークダウンをサポートします。
  • token :コンポーネントの使用方法を示すちょっとしたコード。

レンダリングドキュメント

コンポーネントのドキュメントも簡単にレンダリングできます。 propDoc コンポーネントを追加し、ドキュメント化されたコンポーネントをcomponentプロップで渡すだけです。

DocumentationComponent.vue
<template>
  <div>
    <!-- Render the documentation for MyButton -->
    <prop-doc :component="MyButton"></prop-doc>
  </div>
</template>

<script>
import propDoc from 'propdoc';
import MyButton from './MyButton.vue';

export default {
  components: {
    propDoc
  },

  data() {
    return {
      MyButton
    }
  }
}
</script>