jsdoc-vuex-plugin

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.
 */

(inner) Getters :object

Name	Returns Type	Returns State Property	Description
getBoolProp	boolean	boolProp	Returns a boolean property.
getStrProp	string	strProp	Returns a string property.
getNumProp	number	numProp	Returns a property that is a number.

Type:

• object

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.
 */

(inner) Mutations :object

Name	Accepts Type	Mutates State Property	Description
setBoolProp	boolean	boolProp	Sets the state boolean property.
setStrProp	string	strProp	Sets the state string property.
setNumProp	number	numProp	Sets the state numerical property.

Type:

• object

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}`);
}

action updateTrackingLb(metric) → {void}

Blah blah blah description.
Vuex Action => Mutates state property strProp

Parameters:

Name	Type	Description
word	string	A string parameter for example purposes.

Returns:

void

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.