docs(eslint-plugin): enforce a heading for each rule option (typescript-eslint#8015)

* docs(eslint-plugin): enforce a heading for each rule option

* Fix lint

Author: JoshuaKGoldberg

Diff for: .cspell.json

@@ -72,6 +72,7 @@
     "declarators",
     "destructure",
     "destructured",
+    "destructures",
     "discoverability",
     "dprint",
     "errored",

Diff for: packages/eslint-plugin/docs/rules/explicit-member-accessibility.md

@@ -164,7 +164,7 @@ class Animal {
 }
 ```
 
-### Overrides
+### `overrides`
 
 There are three ways in which an override can be used.
 
@@ -312,7 +312,7 @@ class Animal {
 }
 ```
 
-### Except specific methods
+### `ignoredMethodNames`
 
 If you want to ignore some specific methods, you can do it by specifying method names. Note that this option does not care for the context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly.
 e.g. `[ { ignoredMethodNames: ['specificMethod', 'whateverMethod'] } ]`

Diff for: packages/eslint-plugin/docs/rules/no-empty-interface.md

@@ -50,20 +50,9 @@ interface Baz extends Foo, Bar {}
 
 ## Options
 
-This rule accepts a single object option with the following default configuration:
-
-```json
-{
-  "@typescript-eslint/no-empty-interface": [
-    "error",
-    {
-      "allowSingleExtends": false
-    }
-  ]
-}
-```
+### `allowSingleExtends`
 
-- `allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members
+`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members
 
 ## When Not To Use It
 

Diff for: packages/eslint-plugin/docs/rules/no-explicit-any.md

@@ -94,6 +94,13 @@ function greet(param: Array<string>): Array<string> {}
 
 ## Options
 
+### `fixToUnknown`
+
+By default, this rule will not provide automatic ESLint _fixes_: only opt-in _suggestions_.
+Switching types to `unknown` is safer but is likely to cause additional type errors.
+
+Enabling `{ "fixToUnknown": true }` gives the rule an auto-fixer to replace `: any` with `: unknown`.
+
 ### `ignoreRestArgs`
 
 A boolean to specify if arrays from the rest operator are considered okay. `false` by default.

Diff for: packages/eslint-plugin/docs/rules/no-meaningless-void-operator.md

@@ -44,6 +44,8 @@ void bar(); // discarding a number
 
 ## Options
 
+### `checkNever`
+
 `checkNever: true` will suggest removing `void` when the argument has type `never`.
 
 ## When Not To Use It

Diff for: packages/eslint-plugin/docs/rules/no-misused-promises.md

@@ -17,7 +17,7 @@ See [`no-floating-promises`](./no-floating-promises.md) for detecting unhandled
 
 ## Options
 
-### `"checksConditionals"`
+### `checksConditionals`
 
 If you don't want to check conditionals, you can configure the rule with `"checksConditionals": false`:
 
@@ -73,7 +73,7 @@ while (await promise) {
 
 <!--/tabs-->
 
-### `"checksVoidReturn"`
+### `checksVoidReturn`
 
 Likewise, if you don't want to check functions that return promises where a void return is
 expected, your configuration will look like this:
@@ -182,7 +182,7 @@ eventEmitter.on('some-event', () => {
 
 <!--/tabs-->
 
-### `"checksSpreads"`
+### `checksSpreads`
 
 If you don't want to check object spreads, you can add this configuration:
 

Diff for: packages/eslint-plugin/docs/rules/no-this-alias.md

@@ -33,6 +33,75 @@ setTimeout(() => {
 
 ## Options
 
+### `allowDestructuring`
+
+It can sometimes be useful to destructure properties from a class instance, such as retrieving multiple properties from the instance in one of its methods.
+`allowDestructuring` allows those destructures and is `true` by default.
+You can explicitly disallow them by setting `allowDestructuring` to `false`.
+
+Examples of code for the `{ "allowDestructuring": false }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    const { props, state } = this;
+
+    console.log(props);
+    console.log(state);
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowDestructuring": false }'
+class ComponentLike {
+  props: unknown;
+  state: unknown;
+
+  render() {
+    console.log(this.props);
+    console.log(this.state);
+  }
+}
+```
+
+### `allowedNames`
+
+`no-this-alias` can alternately be used to allow only a specific list of names as `this` aliases.
+We recommend against this except as a transitory step towards fixing all rule violations.
+
+Examples of code for the `{ "allowedNames": ["self"] }` option:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const that = this;
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowedNames": ["self"] }'
+class Example {
+  method() {
+    const self = this;
+  }
+}
+```
+
 ## When Not To Use It
 
 If your project is structured in a way that it needs to assign `this` to variables, this rule is likely not for you.

Diff for: packages/eslint-plugin/docs/rules/parameter-properties.md

@@ -19,7 +19,7 @@ It may take an options object containing either or both of:
 - `"allow"`: allowing certain kinds of properties to be ignored
 - `"prefer"`: either `"class-property"` _(default)_ or `"parameter-property"`
 
-### `"allow"`
+### `allow`
 
 If you would like to ignore certain kinds of properties then you may pass an object containing `"allow"` as an array of any of the following options:
 
@@ -45,7 +45,7 @@ For example, to ignore `public` properties:
 }
 ```
 
-### `"prefer"`
+### `prefer`
 
 By default, the rule prefers class property (`"class-property"`).
 You can switch it to instead preferring parameter property with (`"parameter-property"`).

Diff for: packages/eslint-plugin/docs/rules/prefer-literal-enum-member.md

@@ -61,7 +61,9 @@ enum Valid {
 
 ## Options
 
-- `allowBitwiseExpressions` set to `true` will allow you to use bitwise expressions in enum initializer (Default: `false`).
+### `allowBitwiseExpressions`
+
+When set to `true` will allow you to use bitwise expressions in enum initializer (default: `false`).
 
 Examples of code for the `{ "allowBitwiseExpressions": true }` option:
 

Diff for: packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.md

@@ -167,6 +167,16 @@ foo ?? 'a string';
 
 Also, if you would like to ignore all primitives types, you can set `ignorePrimitives: true`. It is equivalent to `ignorePrimitives: { string: true, number: true, bigint: true, boolean: true }`.
 
+### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing`
+
+If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.
+
+Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless.
+
+You should be using `strictNullChecks` to ensure complete type-safety in your codebase.
+
+If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option.
+
 ## When Not To Use It
 
 If you are not using TypeScript 3.7 (or greater), then you will not be able to use this rule, as the operator is not supported.

Diff for: packages/eslint-plugin/docs/rules/promise-function-async.md

@@ -58,6 +58,74 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
 }
 ```
 
+## Options
+
+### `allowAny`
+
+Whether to ignore functions that return `any` and `unknown`.
+If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors.
+
+Examples of code with `{ "allowAny": false }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowAny": false }'
+const returnsAny = () => ({}) as any;
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowAny": false }'
+const returnsAny = async () => ({}) as any;
+```
+
+### `allowedPromiseNames`
+
+For projects that use constructs other than the global built-in `Promise` for asynchronous code.
+This option allows specifying string names of classes or interfaces that cause a function to be checked as well.
+
+Examples of code with `{ "allowedPromiseNames": ["Bluebird"] }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = () => new Bluebird(() => {});
+```
+
+#### ✅ Correct
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = async () => new Bluebird(() => {});
+```
+
+### `checkArrowFunctions`
+
+Whether to check arrow functions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionDeclarations`
+
+Whether to check standalone function declarations.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionExpressions`
+
+Whether to check inline function expressions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkMethodDeclarations`
+
+Whether to check methods on classes and object literals
+`true` by default, but can be set to `false` to ignore them.
+
 ## When Not To Use It
 
 This rule can be difficult to enable on projects that use APIs which require functions to always be `async`.

Diff for: packages/eslint-plugin/docs/rules/sort-type-constituents.md

@@ -82,6 +82,46 @@ type T4 =
 
 ## Options
 
+### `checkIntersections`
+
+Whether to check intersection types (`&`).
+
+Examples of code with `{ "checkIntersections": true }` (the default):
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "checkIntersections": true }'
+type ExampleIntersection = B & A;
+```
+
+#### ✅ Correct
+
+```ts option='{ "checkIntersections": true }'
+type ExampleIntersection = A & B;
+```
+
+### `checkUnions`
+
+Whether to check union types (`|`).
+
+Examples of code with `{ "checkUnions": true }` (the default):
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "checkUnions": true }'
+type ExampleUnion = B | A;
+```
+
+#### ✅ Correct
+
+```ts option='{ "checkUnions": true }'
+type ExampleUnion = A | B;
+```
+
 ### `groupOrder`
 
 Each constituent of the type is placed into a group, and then the rule sorts alphabetically within each group.
@@ -100,6 +140,22 @@ The ordering of groups is determined by this option.
 - `union` - Union types (`A | B`)
 - `nullish` - `null` and `undefined`
 
+For example, configuring the rule with `{ "groupOrder": ["literal", "nullish" ]}`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts option='{ "groupOrder": ["literal", "nullish" ]}'
+type ExampleGroup = null | 123;
+```
+
+#### ✅ Correct
+
+```ts option='{ "groupOrder": ["literal", "nullish" ]}'
+type ExampleGroup = 123 | null;
+```
+
 ## When Not To Use It
 
 This rule is purely a stylistic rule for maintaining consistency in your project.