@bochen/vue-prop-doc

vue-prop-doc

quick and easy documentation of Vue.js components

installation

npm install --save propdoc

example output

This example was solely generated based on the extra fields described below.

features

propdoc proposes a new way of documenting Vue components, by including some (or all) of the documentation in the component itself.

Benefits:

• props can be directly annotated, making documentation essentially the same as commenting a prop
• Documentation can live directly in the component - thus centralizing the documentation and hopefully helping the development/documentation cycle

Downsides:

• If all documentation is built into the options object, the component will use additional space
  • This can be mitigated by externalizing the larger proposed keys such as description and token

new keys for your components

This example showcases all of what propdoc would parse, however, none are required to be used and will not be output if absent.

export default {
  name: 'checkbox',
  introduction: 'an amazing checkbox',
  description: `
  This \`checkbox\` is amazing, you should _check_ it out.
  `,
  token: "<checkbox label='foo'></checkbox>",
  props: {
    label: {
      type: String,
      default: '',
      note: "a label to be appended after the checkbox"
    }
  }
}

note

note is used alongside expanded (object-style) props to describe that prop in more detail

introduction

a brief summary of what the component is or does

description

a more in-depth documentation of the component, will be parsed using Markdown. Note that code will need to be escaped if it's inside of a Javascript string literal.

token

a quick example of the component's actual use, great for providing a way to quickly copy/paste in the future

use in your documentation

<script>
import propDoc from 'propdoc'
import myComponent from './myComponent.vue'

export default {
  components: { propDoc },
  // bind your component to use propdoc's native template output
  data() {
    return { documentMe: myComponent }
  },
  // or call getDoc() and use the same data in your own template
  computed: {
    myComponentDoc() { return propDoc.getDoc(myComponent) }
  }
}
</script>

<template>
  <section>
    <prop-doc :component="documentMe"></prop-doc>
    <div>
      <h1>{{ myComponentDoc.name }}</h1>
      <p>{{ myComponentDoc.introduction }}</p>
    </div>
  </section>
</template>

props

• component: required and should be the component object itself
• documentation: optional, can be any subset of component, and will take precedence; useful for two functions
  • if the component's name or other fields should be output differently for documentation
  • for the optional documentation fields, as these will cause some additional space to be used by your components if not separated

slots

Two named slots are available for adding content to what propdoc emits

• pre-use will add content before the description and token fields
• pre-props will add content before the prop tables are emitted

propDoc.getDoc

available in v0.8 onward

propDoc.getDoc(component, documentation)

• merges the arguments passed to it, then processes them as described above in keys
• the props object will be converted into an array instead of an object to simplify parsing in your template
  • essentially this means you can do v-for="prop in myDocumentedComponent.props" and then prop.name instead of having to separate out the key/value