eslint-config-tjw-jsdoc

The Jared Wilcurt's strict JSDoc ESLint rules for obsessives.

Using this

1. npm install --save-dev eslint-plugin-jsdoc eslint-config-tjw-jsdoc
2. In your .eslitrc.js add tjw-jsdoc to your extends like so:

   module.exports = {
     extends: [
       'tjw-jsdoc'
     ]
   };

What does it look like?

The linter will enforce the formatting and types for functions arguments/returns.

Below is an example function and what the formatting looks like for its comment block.

• A description is required (and must end in a period). Followed by a return. This explains what the function does, and why it exists.
• All arguments and return require a type, but can be an imported interface if complex/reusable. (see: example)
• All argument names must match the code (to ensure the comment isn't outdated).
• All arguments and return must have description text explaining what they are/why they exist.
• If the function returns a value, then the @return and a description will be required.
• If the funciton has no return, then the comment must remove the @return line.
• You can optionally include an @example after the main description and it will be formatted.
• Almost all formatting can be applied automatically with ESLint's --fix.

const { OPTIONS } = require('../api-type-definitions.js');

/**
 * Generic validation method to ensure a specific key on the options
 * object is either a string, or removed.
 *
 * @param  {OPTIONS} options  User's options
 * @param  {string}  key      The key within the OS object to be validated as an optional string
 * @return {OPTIONS}          Validated or mutated user options
 */
function validateOptionalString (options, key) {
  if (
    typeof(options) === 'object' &&
    Object(options).hasOwnProperty(key) &&
    typeof(options[key]) !== 'string'
  ) {
    console.warn(options, 'Optional ' + key + ' must be a string');
    delete options[key];
  }
  return options;
}

Pairs really well with:

• Sublime Text plugin - DocBlockr - Best in class
• VS Codium plugin - VS DocBlockr - Not as good as the SublimeText one, but not bad
• IntelliJ based editors (WebStorm, etc) have a built in plugin you can enable, but it's not open source, it's handled by Jet Brains, and it's almost completely useless. But you can still enable it and try it out. If enough people turn it on, maybe they'll prioritize making it better.

But the point of using ESLint to enforce this is so that you don't have to do editor-specific things. Any team can adopt this approach and each dev can make ESLint work with whatever tools they use.

See also:

• eslint-config-tjw-base - Basic JavaScript Linting
• eslint-config-tjw-import - Lint import/require statements
• eslint-config-tjw-jest - Lint Jest/Vitest Unit Tests
• eslint-config-tjw-jsdoc - Enforce JSDoc comment blocks
• eslint-config-tjw-vue - Lint Vue files