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:
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* @property* @property* @property*/
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* @getter* @getter* @getter*/
Type:
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* @mutator* @mutator* @mutator*/
Type:
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}`);}
Parameters:
<span class="type-signature"><span class="icon green">action</span> </span>updateTrackingLb<span class="signature">(metric)</span><span class="type-signature"> → {void}</span>
</h4>
Vuex Action => Mutates state property
strProp
Parameters:
Name | Type | Description |
---|---|---|
word |
string | A string parameter for example purposes. |
Returns:
voidContributing
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.