[Docs] Consistent rule descriptions and doc sections

.eslintrc

@@ -50,6 +50,7 @@
         }],
 
         "eslint-plugin/consistent-output": 0,
+        "eslint-plugin/require-meta-docs-description": [2, { "pattern": "^(Enforce|Require|Disallow)" }],
         "eslint-plugin/require-meta-schema": 0,
         "eslint-plugin/require-meta-type": 0
     },

CHANGELOG.md

@@ -37,7 +37,9 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 * [Tests] [`function-component-definition`]: add passing test cases ([#3355][] @TildaDares)
 * [Docs] [`jsx-no-target-blank`]: Fix link to link-type-noreferrer ([#3319][] @Luccasoli)
 * [Docs] document which rules provide suggestions ([#3359][] @bmish)
+* [Docs] Consistent rule descriptions and doc sections ([#3361][] @bmish)
 
+[#3361]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3361
 [#3359]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3359
 [#3355]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3355
 [#3353]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3353

docs/rules/button-has-type.md

@@ -1,4 +1,4 @@
-# Prevent usage of `button` elements without an explicit `type` attribute (react/button-has-type)
+# Disallow usage of `button` elements without an explicit `type` attribute (react/button-has-type)
 
 The default value of `type` attribute for `button` HTML element is `"submit"` which is often not the desired behavior and may lead to unexpected page reloads.
 This rules enforces an explicit `type` attribute for all the `button` elements and checks that its value is valid per spec (i.e., is one of `"button"`, `"submit"`, and `"reset"`).

docs/rules/display-name.md

@@ -1,4 +1,4 @@
-# Prevent missing displayName in a React component definition (react/display-name)
+# Disallow missing displayName in a React component definition (react/display-name)
 
 DisplayName allows you to name your component. This name is used by React in debugging messages.
 

docs/rules/forbid-component-props.md

@@ -1,4 +1,4 @@
-# Forbid certain props on Components (react/forbid-component-props)
+# Disallow certain props on components (react/forbid-component-props)
 
 By default this rule prevents passing of [props that add lots of complexity](https://medium.com/brigade-engineering/don-t-pass-css-classes-between-components-e9f7ab192785) (`className`, `style`) to Components. This rule only applies to Components (e.g. `<Foo />`) and not DOM nodes (e.g. `<div />`). The list of forbidden props can be customized with the `forbid` option.
 

docs/rules/forbid-dom-props.md

@@ -1,4 +1,4 @@
-# Forbid certain props on DOM Nodes (react/forbid-dom-props)
+# Disallow certain props on DOM Nodes (react/forbid-dom-props)
 
 This rule prevents passing of props to elements. This rule only applies to DOM Nodes (e.g. `<div />`) and not Components (e.g. `<Component />`).
 The list of forbidden props can be customized with the `forbid` option.

docs/rules/forbid-elements.md

@@ -1,4 +1,4 @@
-# Forbid certain elements (react/forbid-elements)
+# Disallow certain elements (react/forbid-elements)
 
 You may want to forbid usage of certain elements in favor of others, (e.g. forbid all `<div />` and use `<Box />` instead). This rule allows you to configure a list of forbidden elements and to specify their desired replacements.
 

docs/rules/forbid-foreign-prop-types.md

@@ -1,4 +1,4 @@
-# Forbid foreign propTypes (react/forbid-foreign-prop-types)
+# Disallow using another component's propTypes (react/forbid-foreign-prop-types)
 
 This rule forbids using another component's prop types unless they are explicitly imported/exported. This allows people who want to use [babel-plugin-transform-react-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types) to remove propTypes from their components in production builds, to do so safely.
 

docs/rules/forbid-prop-types.md

@@ -1,4 +1,4 @@
-# Forbid certain propTypes (react/forbid-prop-types)
+# Disallow certain propTypes (react/forbid-prop-types)
 
 By default this rule prevents vague prop types with more specific alternatives available (`any`, `array`, `object`), but any prop type can be disabled if desired. The defaults are chosen because they have obvious replacements. `any` should be replaced with, well, anything. `array` and `object` can be replaced with `arrayOf` and `shape`, respectively.
 

docs/rules/jsx-boolean-value.md

@@ -2,10 +2,14 @@
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-[When using a boolean attribute in JSX](https://facebook.github.io/react/docs/jsx-in-depth.html#boolean-attributes), you can set the attribute value to `true` or omit the value. This rule will enforce one or the other to keep consistency in your code.
+[When using a boolean attribute in JSX](https://facebook.github.io/react/docs/jsx-in-depth.html#boolean-attributes), you can set the attribute value to `true` or omit the value.
 
 ## Rule Details
 
+This rule will enforce one or the other to keep consistency in your code.
+
+## Rule Options
+
 This rule takes two arguments. If the first argument is `"always"` then it warns whenever an attribute is missing its value. If `"never"` then it warns if an attribute has a `true` value. The default value of this option is `"never"`.
 
 The second argument is optional: if provided, it must be an object with a `"never"` property (if the first argument is `"always"`), or an `"always"` property (if the first argument is `"never"`). This property’s value must be an array of strings representing prop names.

docs/rules/jsx-child-element-spacing.md

@@ -1,4 +1,4 @@
-# Enforce or disallow spaces inside of curly braces in JSX attributes and expressions. (react/jsx-child-element-spacing)
+# Enforce or disallow spaces inside of curly braces in JSX attributes and expressions (react/jsx-child-element-spacing)
 
 ## Rule Details
 

docs/rules/jsx-closing-bracket-location.md

@@ -1,4 +1,4 @@
-# Validate closing bracket location in JSX (react/jsx-closing-bracket-location)
+# Enforce closing bracket location in JSX (react/jsx-closing-bracket-location)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-closing-tag-location.md

@@ -1,4 +1,4 @@
-# Validate closing tag location in JSX (react/jsx-closing-tag-location)
+# Enforce closing tag location for multiline JSX (react/jsx-closing-tag-location)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-curly-brace-presence.md

@@ -1,4 +1,4 @@
-# Enforce curly braces or disallow unnecessary curly braces in JSX props and/or children. (react/jsx-curly-brace-presence)
+# Disallow unnecessary JSX expressions when literals alone are sufficient or enforce JSX expressions on literals in JSX children or attributes (react/jsx-curly-brace-presence)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-curly-newline.md

@@ -1,4 +1,4 @@
-# Enforce linebreaks in curly braces in JSX attributes and expressions. (react/jsx-curly-newline)
+# Enforce consistent linebreaks in curly braces in JSX attributes and expressions (react/jsx-curly-newline)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-curly-spacing.md

@@ -1,4 +1,4 @@
-# Enforce or disallow spaces inside of curly braces in JSX attributes and expressions. (react/jsx-curly-spacing)
+# Enforce or disallow spaces inside of curly braces in JSX attributes and expressions (react/jsx-curly-spacing)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-equals-spacing.md

@@ -1,4 +1,4 @@
-# Enforce or disallow spaces around equal signs in JSX attributes. (react/jsx-equals-spacing)
+# Enforce or disallow spaces around equal signs in JSX attributes (react/jsx-equals-spacing)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
@@ -8,7 +8,7 @@ Some style guides require or disallow spaces around equal signs.
 
 This rule will enforce consistency of spacing around equal signs in JSX attributes, by requiring or disallowing one or more spaces before and after `=`.
 
-### Options
+## Rule Options
 
 There are two options for the rule:
 
@@ -21,7 +21,7 @@ Depending on your coding conventions, you can choose either option by specifying
 "react/jsx-equals-spacing": [2, "always"]
 ```
 
-#### never
+### never
 
 Examples of **incorrect** code for this rule, when configured with `"never"`:
 
@@ -39,7 +39,7 @@ Examples of **correct** code for this rule, when configured with `"never"`:
 <Hello {...props} />;
 ```
 
-#### always
+### always
 
 Examples of **incorrect** code for this rule, when configured with `"always"`:
 

docs/rules/jsx-filename-extension.md

@@ -1,4 +1,4 @@
-# Restrict file extensions that may contain JSX (react/jsx-filename-extension)
+# Disallow file extensions that may contain JSX (react/jsx-filename-extension)
 
 ## Rule Details
 

docs/rules/jsx-first-prop-new-line.md

@@ -1,4 +1,4 @@
-# Configure the position of the first property (react/jsx-first-prop-new-line)
+# Enforce proper position of the first property in JSX (react/jsx-first-prop-new-line)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-fragments.md

@@ -2,7 +2,11 @@
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
-In JSX, a React fragment is created either with `<React.Fragment>...</React.Fragment>`, or, using the shorthand syntax, `<>...</>`. This rule allows you to enforce one way or the other.
+In JSX, a React fragment is created either with `<React.Fragment>...</React.Fragment>`, or, using the shorthand syntax, `<>...</>`.
+
+## Rule Details
+
+This rule allows you to enforce one way or the other.
 
 Support for fragments was added in React v16.2, so the rule will warn on either of these forms if an older React version is specified in [shared settings][shared_settings].
 

docs/rules/jsx-indent-props.md

@@ -1,4 +1,4 @@
-# Validate props indentation in JSX (react/jsx-indent-props)
+# Enforce props indentation in JSX (react/jsx-indent-props)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-indent.md

@@ -1,4 +1,4 @@
-# Validate JSX indentation (react/jsx-indent)
+# Enforce JSX indentation (react/jsx-indent)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-key.md

@@ -1,4 +1,4 @@
-# Detect missing `key` prop (react/jsx-key)
+# Disallow missing `key` props in iterators/collection literals (react/jsx-key)
 
 Warn if an element that likely requires a `key` prop--namely, one present in an
 array literal or an arrow function expression.

docs/rules/jsx-max-depth.md

@@ -1,4 +1,4 @@
-# Validate JSX maximum depth (react/jsx-max-depth)
+# Enforce JSX maximum depth (react/jsx-max-depth)
 
 This option validates a specific depth for JSX.
 

docs/rules/jsx-max-props-per-line.md

@@ -1,4 +1,4 @@
-# Limit maximum of props on a single line in JSX (react/jsx-max-props-per-line)
+# Enforce maximum of props on a single line in JSX (react/jsx-max-props-per-line)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-no-bind.md

@@ -1,4 +1,4 @@
-# No `.bind()` or Arrow Functions in JSX Props (react/jsx-no-bind)
+# Disallow `.bind()` or arrow functions in JSX props (react/jsx-no-bind)
 
 A `bind` call or [arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) in a JSX prop will create a brand new function on every single render. This is bad for performance, as it may cause unnecessary re-renders if a brand new function is passed as a prop to a component that uses reference equality check on the prop to determine if it should update.
 

docs/rules/jsx-no-comment-textnodes.md

@@ -1,4 +1,4 @@
-# Prevent comments from being inserted as text nodes (react/jsx-no-comment-textnodes)
+# Disallow comments from being inserted as text nodes (react/jsx-no-comment-textnodes)
 
 This rule prevents comment strings (e.g. beginning with `//` or `/*`) from being accidentally
 injected as a text node in JSX statements.

docs/rules/jsx-no-constructed-context-values.md

@@ -1,4 +1,4 @@
-# Prevent react contexts from taking non-stable values (react/jsx-no-constructed-context-values)
+# Disallows JSX context provider values from taking values that will cause needless rerenders (react/jsx-no-constructed-context-values)
 
 This rule prevents non-stable values (i.e. object identities) from being used as a value for `Context.Provider`.
 

docs/rules/jsx-no-duplicate-props.md

@@ -1,4 +1,4 @@
-# Prevent duplicate properties in JSX (react/jsx-no-duplicate-props)
+# Disallow duplicate properties in JSX (react/jsx-no-duplicate-props)
 
 Creating JSX elements with duplicate props can cause unexpected behavior in your application.
 

docs/rules/jsx-no-leaked-render.md

@@ -1,4 +1,4 @@
-# Prevent problematic leaked values from being rendered (react/jsx-no-leaked-render)
+# Disallow problematic leaked values from being rendered (react/jsx-no-leaked-render)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
@@ -139,7 +139,7 @@ const Component = ({ elements }) => {
 }
 ```
 
-### Options
+## Rule Options
 
 The supported options are:
 

docs/rules/jsx-no-literals.md

@@ -1,4 +1,4 @@
-# Prevent usage of string literals in JSX (react/jsx-no-literals)
+# Disallow usage of string literals in JSX (react/jsx-no-literals)
 
 There are a few scenarios where you want to avoid string literals in JSX. You may want to enforce consistency, reduce syntax highlighting issues, or ensure that strings are part of a translation system.
 

docs/rules/jsx-no-script-url.md

@@ -1,4 +1,4 @@
-# Prevent usage of `javascript:` URLs (react/jsx-no-script-url)
+# Disallow usage of `javascript:` URLs (react/jsx-no-script-url)
 
 **In React 16.9** any URLs starting with `javascript:` [scheme](https://wiki.whatwg.org/wiki/URL_schemes#javascript:_URLs) log a warning.
 React considers the pattern as a dangerous attack surface, see [details](https://reactjs.org/blog/2019/08/08/react-v16.9.0.html#deprecating-javascript-urls).

docs/rules/jsx-no-target-blank.md

@@ -1,4 +1,4 @@
-# Prevent usage of unsafe `target='_blank'` (react/jsx-no-target-blank)
+# Disallow `target="_blank"` attribute without `rel="noreferrer"` (react/jsx-no-target-blank)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-one-expression-per-line.md

@@ -1,4 +1,4 @@
-# One JSX Element Per Line (react/jsx-one-expression-per-line)
+# Require one JSX element per line (react/jsx-one-expression-per-line)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 

docs/rules/jsx-props-no-spreading.md

@@ -1,4 +1,4 @@
-# Disallow JSX props spreading (react/jsx-props-no-spreading)
+# Disallow JSX prop spreading (react/jsx-props-no-spreading)
 
 Enforces that there is no spreading for any JSX attribute. This enhances readability of code by being more explicit about what props are received by the component. It is also good for maintainability by avoiding passing unintentional extra props and allowing react to emit warnings when invalid HTML props are passed to HTML elements.
 

docs/rules/jsx-space-before-closing.md

@@ -1,4 +1,4 @@
-# Validate spacing before closing bracket in JSX (react/jsx-space-before-closing)
+# Enforce spacing before closing bracket in JSX (react/jsx-space-before-closing)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
@@ -10,6 +10,8 @@ Enforce or forbid spaces before the closing bracket of self-closing JSX elements
 
 This rule checks if there is one or more spaces before the closing bracket of self-closing JSX elements.
 
+## Rule Options
+
 This rule takes one argument. If it is `"always"` then it warns whenever a space is missing before the closing bracket. If `"never"` then it warns if a space is present before the closing bracket. The default value of this option is `"always"`.
 
 Examples of **incorrect** code for this rule, when configured with `"always"`:

docs/rules/jsx-tag-spacing.md

@@ -1,4 +1,4 @@
-# Validate whitespace in and around the JSX opening and closing brackets (react/jsx-tag-spacing)
+# Enforce whitespace in and around the JSX opening and closing brackets (react/jsx-tag-spacing)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
@@ -8,6 +8,8 @@ Enforce or forbid spaces after the opening bracket, before the closing bracket,
 
 This rule checks the whitespace inside and surrounding the JSX syntactic elements.
 
+## Rule Options
+
 This rule takes one argument, an object with 4 possible keys: `closingSlash`, `beforeSelfClosing`, `afterOpening`, and `beforeClosing`. Each key can receive the value `"allow"` to disable that specific check.
 
 The default values are:

docs/rules/jsx-uses-react.md

@@ -1,4 +1,4 @@
-# Prevent React to be incorrectly marked as unused (react/jsx-uses-react)
+# Disallow React to be incorrectly marked as unused (react/jsx-uses-react)
 
 JSX expands to a call to `React.createElement`, a file which includes `React`
 but only uses JSX should consider the `React` variable as used.
@@ -45,4 +45,4 @@ var Hello = <div>Hello {this.props.name}</div>;
 
 If you are not using JSX, if React is declared as global variable, or if you do not use the `no-unused-vars` rule.
 
-If you are using the [new JSX transform from React 17](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html#removing-unused-react-imports), you should disable this rule by extending [`react/jsx-runtime`](https://github.com/jsx-eslint/eslint-plugin-react/blob/HEAD/index.js#L163-L176) in your eslint config (add `"plugin:react/jsx-runtime"` to `"extends"`).
+If you are using the [new JSX transform from React 17](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html#removing-unused-react-imports), you should disable this rule by extending [`react/jsx-runtime`](https://github.com/jsx-eslint/eslint-plugin-react/blob/HEAD/index.js#L163-L176) in your eslint config (add `"plugin:react/jsx-runtime"` to `"extends"`).

docs/rules/jsx-uses-vars.md

@@ -1,4 +1,4 @@
-# Prevent variables used in JSX to be incorrectly marked as unused (react/jsx-uses-vars)
+# Disallow variables used in JSX to be incorrectly marked as unused (react/jsx-uses-vars)
 
 Since 0.17.0 the `eslint` `no-unused-vars` rule does not detect variables used in JSX ([see details](https://eslint.org/blog/2015/03/eslint-0.17.0-released#changes-to-jsxreact-handling)). This rule will find variables used in JSX and mark them as used.
 

docs/rules/jsx-wrap-multilines.md

@@ -1,4 +1,4 @@
-# Prevent missing parentheses around multiline JSX (react/jsx-wrap-multilines)
+# Disallow missing parentheses around multiline JSX (react/jsx-wrap-multilines)
 
 🔧 This rule is automatically fixable using the `--fix` [flag](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.
 
@@ -22,6 +22,8 @@ This rule optionally takes a second parameter in the form of an object, containi
 
 Note: conditions are checked by default in declarations or assignments.
 
+## Rule Options
+
 Examples of **incorrect** code for this rule, when configured with `parens` or `parens-new-line`:
 
 ```jsx

docs/rules/no-access-state-in-setstate.md

@@ -1,9 +1,14 @@
-# Prevent using this.state within a this.setState (react/no-access-state-in-setstate)
+# Disallow when this.state is accessed within setState (react/no-access-state-in-setstate)
+
+Usage of `this.state` inside `setState` calls might result in errors when two state calls are called in batch and thus referencing old state and not the current state.
+
+## Rule Details
 
 This rule should prevent usage of `this.state` inside `setState` calls.
-Such usage of `this.state` might result in errors when two state calls are
-called in batch and thus referencing old state and not the current
-state. An example can be an increment function:
+
+## Examples
+
+An example can be an increment function:
 
 ```javascript
 function increment() {