jsdoc-vuex-plugin v1.0.0

jsdoc-vuex-plugin

A JsDoc plugin for documenting Vuex modules.

Why would I do this?

I'm a sucker for clean and concise documentation. I used to document my Vuex modules using namespaces and typedefs already built in in JsDoc, but after a while found these mechanisms frustrating as they just could not do what I wanted them to.

So?

This plugin creates custom tags for Vuex getters, mutations and actions.

Installation

You need to have node-js set up and configured. Next, you need to install JsDoc:

npm i -D jsdoc

After that, you should install this plugin as a global package:

npm i -g jsdoc-vuex-plugin

To enable the plugin in JsDoc, add the relevant configuration option in your jsdoc.conf:

Example:

{
  "tags": {
    "allowUnknownTags": true
  },
  "source": {
    "include": ["."],
    "exclude": [ "node_modules" ],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": ""
  },
  "plugins": ["jsdoc-vuex-plugin"],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  }
}

Run JsDoc with the --config flag and point to the path of your jsdoc.conf.

Vuex tags

The state

I have not bothered to create custom tags for the Vuex state. To document the Vuex state I have selected to simply use the existing @property tag, like so:

/**
 * The Vuex 'state' object.
 * @name State
 * @type {object}
 * @property {boolean} boolProp This property is a boolean.
 * @property {string} strProp This property is a string.
 * @property {number} numProp This property is a number.
 */

Getters

The @getter tag uses the following syntax:

@getter {return_type} getter_name=state_property_returned And a description.

Example:

/**
 * The module 'getters' object.
 * @name Getters
 * @type {object}
 * @getter {boolean} getBoolProp=boolProp Returns a boolean property.
 * @getter {string} getStrProp=strProp Returns a string property.
 * @getter {boolean} getNumProp=numProp Returns a property that is a number.
 */

Mutators

The _@mutator tag uses the following syntax:

@mutator {accepts_type} mutator_name=state_property_to_mutate And a description.

Example:

/**
 * The module 'setters' object.
 * @name Getters
 * @type {object}
 * @mutator {boolean} setBoolProp=boolProp Sets the state boolean property.
 * @mutator {string} setStrProp=strProp Sets the state string property.
 * @mutator {number} setNumProp=numProp Sets the state numerical property.
 */

Actions

The @action tag should not be documented liek an object, but rather like a method. I chose this approach due to their asynchronous nature.

The @action tag should be documented like this:

@action action_name=state_property_affected

Here is an example:

/**
 * Blah blah blah description.
 * @action updateStrProp=strProp
 * @param {string} word A string parameter for example purposes.
 * @returns {void}
 */
updateStrProp({ commit }, word) {
    const ajaxResult = getResult();/// Some Ajax here...
    commit('setStrProp', `${word} blah blah blah ${ajaxResult}`);
}

Contributing

Bug reports and pull requests are welcome.

License

MIT

Special Thanks

To Brad van der Laan who authored the awesome jsdoc-route-plugin, a project that provides custom JsDoc tags inteded to be used when documenting Express routes, and also the project that I very shamelessly used as an example when I wrote this plugin.