81. Documenting components

With Vue Styleguidist now installed and running, let's start documenting our components, beginning with the CartItem component.

Doc blocks

Similar to apiDoc, Vue Styleguidist is going to scan our component files and parse the doc blocks in order to populate the documentation.

The difference between the two, though, is that Vue Styleguidist doesn't strictly rely on block tags. What's just as important is the context of the doc block.

General description

For example, in order to provide a general description of a component, you need to put a doc block directly above the export definition. So let's add a doc block here, and provide a general description of "Cart item.".

There are some block tags that Vue Styleguidist recognizes, though. For example, we can put a @version tag in this block, so let's do that and give it a value of 1.0.0.

client/components/CartItem.vue

<script>
import { currency } from "@/filters";
import Item from "@/store/models/Item";
/**
 * Cart item.
 * @version 1.0.0
 */
export default {...};
</script>

Looking at our docs again and going to the CartItem section, you can see the documentation has now been populated with the info that we just put in that doc block.

Props

One of the most important aspects of a component to document is its inputs. And the most common way to provide input to a component is with props.

To document props, you need to put a doc block directly above the prop you want to document. So let's document the id prop of this component.

First we'll add the doc block, then we can add a description of the prop. Now, remember that the id prop of this component is used to query Vuex ORM for an Item model instance. So let's make the description simple "Item id".

client/components/CartItem.vue

props: {
  /**
   * Item id
   */
  id: {
    type: String,
    required: true
  }
},

Once the site rebuilds, we can now click the "PROPS, METHODS, EVENTS & SLOTS" heading, and you'll see the id prop that we just documented.

What's interesting is that Vue Styleguidist is able to partially auto-document the prop by using the prop definition. So in addition to the description, you'll see the name, type, default value, and so on, which we didn't explicitly provide.

InputMixin

Let's now document the Input Mixin file. Now, the great thing about documenting mixins is that the documentation will automatically flow through to all the components that use it. In this case, all of the form inputs.

So let's begin by adding a doc block above the externalErrors prop. This prop allows the parent component to pass in external errors to an input. So let's give it the description "A reactive array of error message strings that gets merged with local error messages.".

Next, we'll add a doc block to the id prop. This prop is used to link the input to a model instance. So the description of this one will be "The id of the model instance.".

Finally, we'll add a doc block to the model prop with description "The Vuex ORM model that the input will bind to.".

client/mixins/InputMixin.js

props: {
  /**
   * A reactive array of error message strings that gets merged with local error messages.
   */
  externalErrors: {
    type: Array,
    default: []
  },
  /**
   * The id of the model instance.
   */
  id: {
    type: String,
    required: true
  },
  /**
   * The Vuex ORM model that the input will bind to.
   */
  model: {
    type: Function,
    required: true
  }
},

Event

We can also document events triggered from our components, such as the one emitted from the errors watch method down here.

This method gets called whenever the errors array is mutated. The data emitted with the event includes the input's name, and whether or not the input has errors.

So let's place a doc block directly above this line. We'll put a description "Error event.".

We'll also document the event arguments, starting with the name, by adding a @property tag. The first value after this is the {string} data type, followed by the name, which is "name", and the description, which is "Input name.".

We'll then add a second "@property" tag with data type {boolean}, with the name inError, and the description will be "Indicates if the input is in error.".

errors () {
  /**
   * Error event.
   * @property {string} name Input name
   * @property {boolean} inError Indicates if the input is in error
   */
  this.$emit(EVENT_ERROR, this.name, this.errors.length > 0);
}

Once the code rebuilds, let's take a look at one of the input components, like InputArtist, and you'll see the props and event have now been documented.

Usage example

One reason developers may want component documentation is to get an example of how the component can, or should, be used.

For this reason, we're going to provide one or more usage examples of each component in our styleguide.

We can do thie right from within our single-file component files by adding a <docs></docs> tag, like that. We can now add markdown content to the docs tags and Vue Stylguidist will use that as part of the component documentation.

So let's begin by adding a markdown heading here, which will be ### Usage example.

We'll then add an HTML code block by going "...html". Inside this code block let's put an example of how the component should be used. In the case of the CartItem, we can start by putting the <CartItem /> tag.

We'll also need to add the id prop. Let's pretend there's an id value present in the context and bind to that by going :id="id".

<docs>
  ### Usage example
  ``html
  <CartItem
    :id="id"
  />
  ``
</docs>

Looking at the CartItem in the styleguide site now, you can see that markdown has been parsed and inserted into docs and we see our usage example.

Discussion

0 comments