working on a syntax for Herman/Vue component documentation…

herman-docs.vue

<template>…</template>
<style>…</style>

<script>
export default {
  name: 'sample-component',
  group: 'buttons',
  access: 'public',
  description: 'A generic, scrollable modal for forms and longer-form content',
  deprecated: 'This is being replaced by …'
  reusable: true,
  links: {
    'Link description': 'target/url',
    'Another link': 'target/url',
  },
  see: {
    'vue': 'another-component',
    'sass': 'related-mixin',
  },
  since: {
    '0.1.2': 'changelog message',
    '1.0.1': 'changelog message',
  },
  todo: [
    'Todo item',
    'Another todo item',
  ],
  props: {
    myProp: {
      type: Number,
      default: 100,
      description: 'Document the purpose of this property directly inline…',
    },
  },
  events: {
    close: {
      description: 'The user has pressed the close button.',
      arguments: null
    },
    resize: {
      description: 'The user has initiated click-and-drag resizing.',
      arguments: [
        { 
          name: 'dimensions'
          description: 'The new dimensions of the modal.'
          type: Object
          shape: {
            width: Number
          }
        }
      ]
    }
  },
  slots: {
    default: {
      description: 'The main content of the modal.',
      required: true
    },
    header: {
      description: 'The header displayed at the top of the modal. Its content is visually separated by the main content by a darker background color.'
    }
  },
};
</script>

<!-- In case we need longer descriptions… -->
<description>
  ## Allow Markdown Description Here
  
  Or is it reasonable to include markdown
  in the component script,
  using template literals?
</description>

<example description="Render this component with the default prop values…">
  <sample-component />
</example>

<example description="Pass in a value!">
  <sample-component myProp="20" />
</example>