Generate a JSON documentation for a Vue file component

The Vuedoc Parser

Generate a JSON documentation for a SFC Vue component.

Install

npm install --save @vuedoc/parser

Features

Extract the component name (from the name field or from the filename)
Extract the component description
Keywords Support: You can define your own keywords with the @ symbol like
@author Jon Snow
Extract component model
Extract component props
Extract component data
Extract computed properties with dependencies
Extract component events
Extract component slots
Extract component methods
Class Component Support
Vue Property Decorator Support
JSDoc Support ([@param](http://usejsdoc.org/tags-param.html) and
[@return](http://usejsdoc.org/tags-returns.html) tags)

Options

NAMEDESCRIPTIONfilenameThe filename to parse. Required unless filecontent is passedfilecontentThe file content to parse. Required unless filename is passedencodingThe file encoding. Default is 'utf8'featuresThe component features to parse and extract.Default features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'data', 'computed', 'events', 'methods']loadersUse this option to define custom loaders for specific languagesdefaultMethodVisibilityCan be set to 'public' (default), 'protected', or 'private'ignoredVisibilitiesList of ignored visibilities. Default: ['protected', 'private']stringifySet to true to disable parsing of literal values and stringify literal values. Default: false

Note for **stringify** option

By default Vuedoc Parser parses literal values defined in the source code.

This means:

const binVar = 0b111110111 // will be parsed as binVar = 503
const numVar = 1_000_000_000 // will be parsed as numVar = 1000000000

To preserve literal values, set the stringify option to true.

Usage

See test/fixtures/checkbox.vue

for an Vue Component decoration example.

const Vuedoc = require('@vuedoc/parser')
const options = {
  filename: 'test/fixtures/checkbox.vue'
}

Vuedoc.parse(options)
  .then((component) => console.log(component))
  .catch((err) => console.error(err))

This will print this JSON output:

{
  "name": "checkbox" // The component name
  "description": "A simple checkbox component" // The component description
  // Attached component keywords
  "keywords": [
    { "name": "author", "description": "Sébastien" }
  ],
  "props": [ ... ],
  "data": [ ... ],
  "computed": [ ... ],
  "slots": [ ... ],
  "events": [ ... ],
  "methods": [ ... ]
}

See test/fixtures/checkbox-result.json for the complete result.

Syntax

Add component name

By default, Vuedoc Parser use the component’s filename to generate the

component name.

To set a custom name, use the name field like:

export default {
  name: 'my-checkbox'
}

You can also use the @name keyword to set the component name:

/**
 * @name my-checkbox
 */
export default {
  // ...
}

Add component description

To add a component description, just add a comment before the export default

statement like:

/**
 * Component description
 */
export default {
  ...
}

Annotate model, props, data and computed properties

To document props, data or computed properties, use comments like:

export default {
  props: {
    /**
     * Component ID
     */
    id: {
      type: String,
      required: true
    }
  },
  data () {
    return {
      /**
       * Indicates that the control is checked
       */
      isChecked: false
    }
  },
  computed: {
    /**
     * Indicates that the control is selected
     */
    selected () {
      return this.isChecked
    }
  }
}

Vuedoc Parser will automatically extract required and default values for

properties and computed properties dependencies. It will also detect type for

each defined data field.

You can set a custom default value of an prop by using the keyword @default.

export default {
  props: {
    /**
     * Custom default value
     * @default { anything: 'custom default value' }
     */
    custom: {
      type: String,
      default: () => {
        // complex code
        return anythingExpression()
      }
    }
  }
}

To document a v-model prop, a proper way is to use the Vue’s

model field if you use Vue +2.2.0.

export default {
  /**
   * Use `v-model` to define a reactive value of the checkbox
   */
  model: {
    prop: 'checked',
    event: 'change'
  }
}

You can also use the @model keyword on a prop if you use an old Vue version:

export default {
  props: {
    /**
     * The checkbox model
     * @model
     */
    model: {
      type: Array,
      required: true
    }
  }
}

To document Vue array string props, just attach a Vuedoc comment to each prop:

export default {
  props: [
    /**
     * Checkbox ID
     */
    'id',

    /**
     * The checkbox model
     */
    'value'
  ]
}

By default, all extracted things have the public visibility.

To change this for one entry, add @protected or @private keyword.

export default {
  data: () => ({
    /**
     * This will be ignored on parsing
     * @private
     */
    isChecked: false
  })
}

Annotate methods, events and slots

To document methods or events, just add comments before:

export default {
  methods: {
    /**
     * Submit form
     */
    check () {
      /**
       * Emit the `input` event on submit
       */
      this.$emit('input', true)
    }
  }
}

Vuedoc Parser automatically extracts events from component hooks:

export default {
  created () {
    /**
     * Emit on Vue `created` hook
     */
    this.$emit('created', true)
  }
}

Use the JSDoc @param and

@return tags to define parameters and

returning type:

export default {
  methods: {
    /**
     * Submit form
     *
     * @param {object} data - Data to submit
     * @return {boolean} true on success; otherwise, false
     */
    submit (data) {
      /**
       * Emit the `loading` event on submit
       *
       * @arg {boolean} status - The loading status
       */
      this.$emit('loading', true)

      return true
    }
  }
}

Note: @arg is an alias of @param

The parser is also able to extract events and slots from template:

<template>
  <div>
    <!-- Emit the `input` event on submit -->
    <button @click="$emit('input', $event)">Submit</button>
    <!-- Default slot -->
    <slot></slot>
    <!-- Use this slot to set the checkbox label -->
    <slot name="label">Unnamed checkbox</slot>
    <!--
      Slot with keywords and
      multiline description

      @prop {User} user - The current user
      @prop {UserProfile} profile - The current user's profile
    -->
    <slot name="header" v-bind:user="user" v-bind:profile="profile"/>
  </div>
</template>

#documentation #json