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:
Getters
The @getter tag uses the following syntax:
@getter {return_type} getter_name=state_property_returned And a description.
Example:
(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:
Mutators
The _@mutator tag uses the following syntax:
@mutator {accepts_type} mutator_name=state_property_to_mutate And a description.
Example:
(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:
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:
updateStrProp({ commit }, word) {
const ajaxResult = getResult();
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.