eslint-plugin-ignorable-jsdoc v0.1.2

eslint-plugin-ignorable-jsdoc

This plugin wraps both require-jsdoc and valid-jsdoc eslint rules. It adds additional options to both that allow you to skip the jsdoc rules under certian conditions.

I was heavily influenced (and originally cloned from) on eslint-plugin-require-jsdoc-except. This plugin adds both some additional configurations scenarios and support for valid-jsdoc.

Installation

npm i eslint-plugin-ignorable-jsdoc --save-dev

Add the following to your eslint config

{
  "plugins": ["ignorable-jsdoc"],
  "rules": {
    "ignorable-jsdoc/require-jsdoc": [
      "error", {
        ...
      }
    ],
    "ignorable-jsdoc/valid-jsdoc": [
      "error", {
        ...
      }
    ],
    // make sure to shut off the standard rules
    "require-jsdoc": "off",
    "valid-jsdoc": "off"
  }
}

Options

All require-jsdoc and valid-jsdoc work and function in the same way

In addition both rules have the following additional objects

• ignore - A list of names to disable rule for. It can take either an Array of an objecet
  • Array. Any method/funciton/class that matches the string or RegExp string will not requrie a jsdoc or not be validated (this works the same as eslint-plugin-require-jsdoc-except)

    ['constructor', '/skip_[a-z]+/']

  • Object. This is similar but lets you target matches to a specific AST node type. Any of the five types that require-jsdoc and valid-jsdoc target can be used as keys. Values are arrays of strings or RegExp strings.

    {
      MethodDefinition: ['constructor', 'render'],
      ClassDeclaration: [], // ClassDecoration has no affect in `valid-jsdoc`
      FunctionDeclaration: [],
      FunctionExpression: [],
      ArrowFunctionExpression: ['noop'],
    }

• ignoreReactLifecycleMethods - This disables the rule for any react lifecycle methods. It will only do this for appropriate method names inside React Component and PureComponent. It does its best to actaully enforce this based on imports, not just class names, although there are known holes/limitations in the logic. The purpose of this is both to simplify the configuration of this common usecase but to also prevent false positive when other non-react things use the same names.

• ignoreFlowFiles - Will disable the rule for any files with // @flow

Example configuration

I like to use the following configuration

"require-jsdoc-except/require-jsdoc": [ "error", { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true }, "ignore": "constructor", "componentWillMount", "componentDidMount", "componentWillUnmount", "getDerivedStateFromProps", "render", "componentWillUpdate", "componentWillReceiveProps", "shouldComponentUpdate", "componentDidUpdate", "getSnapshotBeforeUpdate", "componentDidCatch" } ], "valid-jsdoc": "error", { } ,

{
  "plugins": ["ignorable-jsdoc"],
  "rules": {
    "ignorable-jsdoc/require-jsdoc": [
      "error", {
        ...,
        "ignoreReactLifecycleMethods": true,
      }
    ],
    "ignorable-jsdoc/valid-jsdoc": [
      "error", {
        ...,
        "ignoreReactLifecycleMethods": true,
        "ignoreFlowFiles": true,
      }
    ],
    // make sure to shut off the standard rules
    "require-jsdoc": "off",
    "valid-jsdoc": "off"
  }
}

This turns off all jsdoc requirements for react lifecycle methods and only requires a comment for flow files (since flow already documents arguments)

A note on flow

If you're using flow you'll also need ot set "parser": "babel-eslint" and npm i babel-eslint --save-dev in your config.

If you're using eslint-plugin-flowtype you already are!

ignoreReactLifecycleMethods impementation and limitations

There are some limitations on the enforcement of ignoreReactLifecycleMethods which attmepts to check your imports to verify that the method name in question is actually on a react component.

Things that work

• Normal defualt import

  import React from 'react';
  
  class MyClass extends React.Component {
    render() {
  
    }
  }

• Normal defualt import with a non-standard name

  import ReactOther from 'react';
  
  class MyClass extends ReactOther.Component {
    render() {
  
    }
  }

• Normal namesapce import

  import * as React from 'react';
  
  class MyClass extends React.Component {
    render() {
  
    }
  }

• Normal namesapce import with a non-standard name

  import * as ReactOther from 'react';
  
  class MyClass extends ReactOther.Component {
    render() {
  
    }
  }

• Named import

  import { Component } from 'react';
  
  class MyClass extends Component {
    render() {
  
    }
  }

• commonjs require

  const React = require('react');
  
  class MyClass extends React.Component {
    render() {
  
    }
  }

• commonjs require with descructure

  const { Component } = require('react');
  
  class MyClass extends Component {
    render() {
  
    }
  }

Things that won't work

• Named import with alias. I believe this is possible to implement in the future

  import { Component as OtherComponent } from 'react';
  
  class MyClass extends OtherComponent {
    render() {
  
    }
  }

• commonjs require with descructure and alias. I believe this is possible to implement in the future

  const { Component: OtherComponent } = require('react');
  
  class MyClass extends OtherComponent {
    render() {
  
    }
  }

• declaration and require in seperate statements. I have no intention of implementing this

  let React;
  React = require('react');
  
  class MyClass extends React.Component {
    render() {
  
    }
  }

• round-about-assignment. this would also include getting React from a global (eg React = window.React) I have no intention of implementing this

  let Something = require('react');
  let React = Something;
  
  class MyClass extends React.Component {
    render() {
  
    }
  }

• Importing from somethign other than 'react'. Whether that means reexporting React from something else, or other React-like libraries, like Preact. Its probably possible to add a config option/setting to set a differnet expected import source, but it's not high on my list

  import React from 'my-super-react';
  
  class MyClass extends React.Component {
    render() {
  
    }
  }