Skip to content

A JSDoc plugin for documenting Vuex modules.

Notifications You must be signed in to change notification settings

Elaniobro/vuex-jsdoc

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

33 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

A JSDoc plugin for documenting Vuex modules.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%