Exciting news!Announcing our $4.6M Series Seed. Learn more
Socket
LoveBlogFAQ
Install
Log in

jsdoc-vuex-plugin

Package Overview
Dependencies
1
Maintainers
1
Versions
1
Issues
File Explorer

Advanced tools

jsdoc-vuex-plugin

A JSDoc plug-in to document Vuex modules.

    1.0.0latest

Version published
Maintainers
1
Yearly downloads
11,955
increased by47.19%

Weekly downloads

Readme

Source

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

NameReturns TypeReturns State PropertyDescription
getBoolPropbooleanboolPropReturns a boolean property.
getStrPropstringstrPropReturns a string property.
getNumPropnumbernumPropReturns a property that is a number.
Type:
  • object

Mutators

The [email protected] 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

NameAccepts TypeMutates State PropertyDescription
setBoolPropbooleanboolPropSets the state boolean property.
setStrPropstringstrPropSets the state string property.
setNumPropnumbernumPropSets 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:
NameTypeDescription
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.

Keywords

Socket

Product

Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc