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
andvalid-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'
- 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)
-
ignoreReactLifecycleMethods
- This disables the rule for any react lifecycle methods. It will only do this for appropriate method names inside ReactComponent
andPureComponent
. 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
;Component{} -
Normal defualt import with a non-standard name
;Component{} -
Normal namesapce import
;Component{} -
Normal namesapce import with a non-standard name
;Component{} -
Named import
;{} -
commonjs require
const React = ;Component{} -
commonjs require with descructure
const Component = ;{}
Things that won't work
-
Named import with alias. I believe this is possible to implement in the future
;{} -
commonjs require with descructure and alias. I believe this is possible to implement in the future
const Component: OtherComponent = ;{} -
declaration and require in seperate statements. I have no intention of implementing this
let React;React = ;Component{} -
round-about-assignment. this would also include getting React from a global (eg
React = window.React
) I have no intention of implementing thislet Something = ;let React = Something;Component{} -
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;Component{}