docs: standardized rule docs heading and option-less Options (#4367)

typescript-eslint · Jan 30, 2022 · 04baac8 · 04baac8
1 parent 4a6d217
commit 04baac8
Show file tree

Hide file tree

Showing 125 changed files with 710 additions and 140 deletions.
diff --git a/packages/eslint-plugin/docs/rules/TEMPLATE.md b/packages/eslint-plugin/docs/rules/TEMPLATE.md
@@ -0,0 +1,57 @@
+# `your-rule-name`
+
+Your rule description here.
+
+## Rule Details
+
+To fill out: tell us more about this rule.
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+// To fill out: incorrect code
+```
+
+### ✅ Correct
+
+```ts
+// To fill out: correct code
+```
+
+## Options
+
+```jsonc
+// .eslintrc.json
+{
+  "rules": {
+    "@typescript-eslint/your-rule-name": "error"
+  }
+}
+```
+
+If not configurable: This rule is not configurable.
+
+If configurable...
+
+```ts
+type Options = {
+  someOption?: boolean;
+};
+
+const defaultOptions: Options = {
+  someOption: false,
+};
+```
+
+## When Not To Use It
+
+To fill out: why wouldn't you want to use this rule?
+For example if this rule requires a feature released in a certain TS version.
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [ ] 🔧 Fixable
+- [ ] 💭 Requires type information
diff --git a/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md b/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md
@@ -1,4 +1,6 @@
-# Require that member overloads be consecutive (`adjacent-overload-signatures`)
+# `adjacent-overload-signatures`
+
+Require that member overloads be consecutive.
 
 Grouping overloaded members together can improve readability of the code.
 
@@ -82,6 +84,19 @@ export function foo(n: number): void;
 export function foo(sn: string | number): void;
 ```
 
+## Options
+
+```jsonc
+// .eslintrc.json
+{
+  "rules": {
+    "@typescript-eslint/adjacent-overload-signatures": "error"
+  }
+}
+```
+
+This rule is not configurable.
+
 ## When Not To Use It
 
 If you don't care about the general structure of the code, then you will not need this rule.

diff --git a/packages/eslint-plugin/docs/rules/array-type.md b/packages/eslint-plugin/docs/rules/array-type.md
@@ -1,4 +1,6 @@
-# Requires using either `T[]` or `Array<T>` for arrays (`array-type`)
+# `array-type`
+
+Requires using either `T[]` or `Array<T>` for arrays.
 
 Using the same style for array definitions across your codebase makes it easier for your developers to read and understand the types.
 

diff --git a/packages/eslint-plugin/docs/rules/await-thenable.md b/packages/eslint-plugin/docs/rules/await-thenable.md
@@ -1,4 +1,6 @@
-# Disallows awaiting a value that is not a Thenable (`await-thenable`)
+# `await-thenable`
+
+Disallows awaiting a value that is not a Thenable.
 
 This rule disallows awaiting a value that is not a "Thenable" (an object which has `then` method, such as a Promise).
 While it is valid JavaScript to await a non-`Promise`-like value (it will resolve immediately), this pattern is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
@@ -27,6 +29,19 @@ const createValue = async () => 'value';
 await createValue();
 ```
 
+## Options
+
+```jsonc
+// .eslintrc.json
+{
+  "rules": {
+    "@typescript-eslint/await-thenable": "error"
+  }
+}
+```
+
+This rule is not configurable.
+
 ## When Not To Use It
 
 If you want to allow code to `await` non-Promise values.

diff --git a/packages/eslint-plugin/docs/rules/ban-ts-comment.md b/packages/eslint-plugin/docs/rules/ban-ts-comment.md
@@ -1,4 +1,6 @@
-# Bans `@ts-<directive>` comments from being used or requires descriptions after directive (`ban-ts-comment`)
+# `ban-ts-comment`
+
+Bans `@ts-<directive>` comments from being used or requires descriptions after directive.
 
 TypeScript provides several directive comments that can be used to alter how it processes files.
 Using these to suppress TypeScript Compiler Errors reduces the effectiveness of TypeScript overall.

diff --git a/packages/eslint-plugin/docs/rules/ban-tslint-comment.md b/packages/eslint-plugin/docs/rules/ban-tslint-comment.md
@@ -1,4 +1,6 @@
-# Bans `// tslint:<rule-flag>` comments from being used (`ban-tslint-comment`)
+# `ban-tslint-comment`
+
+Bans `// tslint:<rule-flag>` comments from being used.
 
 Useful when migrating from TSLint to ESLint. Once TSLint has been removed, this rule helps locate TSLint annotations (e.g. `// tslint:disable`).
 

diff --git a/packages/eslint-plugin/docs/rules/ban-types.md b/packages/eslint-plugin/docs/rules/ban-types.md
@@ -1,4 +1,6 @@
-# Bans specific types from being used (`ban-types`)
+# `ban-types`
+
+Bans specific types from being used.
 
 Some builtin types have aliases, some types are considered dangerous or harmful.
 It's often a good idea to ban certain types to help with consistency and safety.

diff --git a/packages/eslint-plugin/docs/rules/brace-style.md b/packages/eslint-plugin/docs/rules/brace-style.md
@@ -1,4 +1,6 @@
-# Enforce consistent brace style for blocks (`brace-style`)
+# `brace-style`
+
+Enforce consistent brace style for blocks.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/class-literal-property-style.md b/packages/eslint-plugin/docs/rules/class-literal-property-style.md
@@ -1,4 +1,6 @@
-# Ensures that literals on classes are exposed in a consistent style (`class-literal-property-style`)
+# `class-literal-property-style`
+
+Ensures that literals on classes are exposed in a consistent style.
 
 When writing TypeScript applications, it's typically safe to store literal values on classes using fields with the `readonly` modifier to prevent them from being reassigned.
 When writing TypeScript libraries that could be used by JavaScript users however, it's typically safer to expose these literals using `getter`s, since the `readonly` modifier is enforced at compile type.

diff --git a/packages/eslint-plugin/docs/rules/comma-dangle.md b/packages/eslint-plugin/docs/rules/comma-dangle.md
@@ -1,4 +1,6 @@
-# Require or disallow trailing comma (`comma-dangle`)
+# `comma-dangle`
+
+Require or disallow trailing comma.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/comma-spacing.md b/packages/eslint-plugin/docs/rules/comma-spacing.md
@@ -1,4 +1,6 @@
-# Enforces consistent spacing before and after commas (`comma-spacing`)
+# `comma-spacing`
+
+Enforces consistent spacing before and after commas.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.md b/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.md
@@ -1,4 +1,6 @@
-# Enforce or disallow the use of the record type (`consistent-indexed-object-style`)
+# `consistent-indexed-object-style`
+
+Enforce or disallow the use of the record type.
 
 TypeScript supports defining object show keys can be flexible using an index signature. TypeScript also has a builtin type named `Record` to create an empty object defining only an index signature. For example, the following types are equal:
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-assertions.md b/packages/eslint-plugin/docs/rules/consistent-type-assertions.md
@@ -1,4 +1,6 @@
-# Enforces consistent usage of type assertions (`consistent-type-assertions`)
+# `consistent-type-assertions`
+
+Enforces consistent usage of type assertions.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-definitions.md b/packages/eslint-plugin/docs/rules/consistent-type-definitions.md
@@ -1,4 +1,6 @@
-# Consistent with type definition either `interface` or `type` (`consistent-type-definitions`)
+# `consistent-type-definitions`
+
+Consistent with type definition either `interface` or `type`.
 
 There are two ways to define a type.
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-exports.md b/packages/eslint-plugin/docs/rules/consistent-type-exports.md
@@ -1,4 +1,6 @@
-# Enforces consistent usage of type exports (`consistent-type-exports`)
+# `consistent-type-exports`
+
+Enforces consistent usage of type exports.
 
 TypeScript 3.8 added support for type-only exports.
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.md b/packages/eslint-plugin/docs/rules/consistent-type-imports.md
@@ -1,4 +1,6 @@
-# Enforces consistent usage of type imports (`consistent-type-imports`)
+# `consistent-type-imports`
+
+Enforces consistent usage of type imports.
 
 TypeScript 3.8 added support for type-only imports.
 Type-only imports allow you to specify that an import can only be used in a type location, allowing certain optimizations within compilers.

diff --git a/packages/eslint-plugin/docs/rules/default-param-last.md b/packages/eslint-plugin/docs/rules/default-param-last.md
@@ -1,4 +1,6 @@
-# Enforce default parameters to be last (`default-param-last`)
+# `default-param-last`
+
+Enforce default parameters to be last.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/dot-notation.md b/packages/eslint-plugin/docs/rules/dot-notation.md
@@ -1,4 +1,6 @@
-# enforce dot notation whenever possible (`dot-notation`)
+# `dot-notation`
+
+enforce dot notation whenever possible.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/explicit-function-return-type.md b/packages/eslint-plugin/docs/rules/explicit-function-return-type.md
@@ -1,4 +1,6 @@
-# Require explicit return types on functions and class methods (`explicit-function-return-type`)
+# `explicit-function-return-type`
+
+Require explicit return types on functions and class methods.
 
 Explicit types for function return values makes it clear to any calling code what type is returned.
 This ensures that the return value is assigned to a variable of the correct type; or in the case

diff --git a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md
@@ -1,4 +1,6 @@
-# Require explicit accessibility modifiers on class properties and methods (`explicit-member-accessibility`)
+# `explicit-member-accessibility`
+
+Require explicit accessibility modifiers on class properties and methods.
 
 Leaving off accessibility modifier and making everything public can make
 your interface hard to use by others.

diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md
@@ -1,4 +1,6 @@
-# Require explicit return and argument types on exported functions' and classes' public class methods (`explicit-module-boundary-types`)
+# `explicit-module-boundary-types`
+
+Require explicit return and argument types on exported functions' and classes' public class methods.
 
 Explicit types for function return values and arguments makes it clear to any calling code what is the module boundary's input and output.
 

diff --git a/packages/eslint-plugin/docs/rules/func-call-spacing.md b/packages/eslint-plugin/docs/rules/func-call-spacing.md
@@ -1,4 +1,6 @@
-# Require or disallow spacing between function identifiers and their invocations (`func-call-spacing`)
+# `func-call-spacing`
+
+Require or disallow spacing between function identifiers and their invocations.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/indent.md b/packages/eslint-plugin/docs/rules/indent.md
@@ -1,4 +1,6 @@
-# Enforce consistent indentation (`indent`)
+# `indent`
+
+Enforce consistent indentation.
 
 ## Warning
 

diff --git a/packages/eslint-plugin/docs/rules/init-declarations.md b/packages/eslint-plugin/docs/rules/init-declarations.md
@@ -1,4 +1,6 @@
-# require or disallow initialization in variable declarations (`init-declarations`)
+# `init-declarations`
+
+require or disallow initialization in variable declarations.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/keyword-spacing.md b/packages/eslint-plugin/docs/rules/keyword-spacing.md
@@ -1,4 +1,6 @@
-# Enforce consistent spacing before and after keywords (`keyword-spacing`)
+# `keyword-spacing`
+
+Enforce consistent spacing before and after keywords.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/lines-between-class-members.md b/packages/eslint-plugin/docs/rules/lines-between-class-members.md
@@ -1,4 +1,6 @@
-# Require or disallow an empty line between class members (`lines-between-class-members`)
+# `lines-between-class-members`
+
+Require or disallow an empty line between class members.
 
 This rule improves readability by enforcing lines between class members. It will not check empty lines before the first member and after the last member. This rule require or disallow an empty line between class members.
 

diff --git a/packages/eslint-plugin/docs/rules/member-delimiter-style.md b/packages/eslint-plugin/docs/rules/member-delimiter-style.md
@@ -1,4 +1,6 @@
-# Require a specific member delimiter style for interfaces and type literals (`member-delimiter-style`)
+# `member-delimiter-style`
+
+Require a specific member delimiter style for interfaces and type literals.
 
 Enforces a consistent member delimiter style in interfaces and type literals. There are three member delimiter styles primarily used in TypeScript:
 

diff --git a/packages/eslint-plugin/docs/rules/member-ordering.md b/packages/eslint-plugin/docs/rules/member-ordering.md
@@ -1,4 +1,6 @@
-# Require a consistent member declaration order (`member-ordering`)
+# `member-ordering`
+
+Require a consistent member declaration order.
 
 A consistent ordering of fields, methods and constructors can make interfaces, type literals, classes and class expressions easier to read, navigate and edit.
 

diff --git a/packages/eslint-plugin/docs/rules/method-signature-style.md b/packages/eslint-plugin/docs/rules/method-signature-style.md
@@ -1,4 +1,6 @@
-# Enforces using a particular method signature syntax. (`method-signature-style`)
+# `method-signature-style`
+
+Enforces using a particular method signature syntax..
 
 There are two ways to define an object/interface function property.
 

diff --git a/packages/eslint-plugin/docs/rules/naming-convention.md b/packages/eslint-plugin/docs/rules/naming-convention.md
@@ -1,4 +1,6 @@
-# Enforces naming conventions for everything across a codebase (`naming-convention`)
+# `naming-convention`
+
+Enforces naming conventions for everything across a codebase.
 
 Enforcing naming conventions helps keep the codebase consistent, and reduces overhead when thinking about how to name a variable.
 Additionally, a well-designed style guide can help communicate intent, such as by enforcing all private properties begin with an `_`, and all global-level constants are written in `UPPER_CASE`.

diff --git a/packages/eslint-plugin/docs/rules/no-array-constructor.md b/packages/eslint-plugin/docs/rules/no-array-constructor.md
@@ -1,4 +1,6 @@
-# Disallow generic `Array` constructors (`no-array-constructor`)
+# `no-array-constructor`
+
+Disallow generic `Array` constructors.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/no-base-to-string.md b/packages/eslint-plugin/docs/rules/no-base-to-string.md
@@ -1,4 +1,6 @@
-# Requires that `.toString()` is only called on objects which provide useful information when stringified (`no-base-to-string`)
+# `no-base-to-string`
+
+Requires that `.toString()` is only called on objects which provide useful information when stringified.
 
 JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
 

diff --git a/packages/eslint-plugin/docs/rules/no-confusing-non-null-assertion.md b/packages/eslint-plugin/docs/rules/no-confusing-non-null-assertion.md
@@ -1,4 +1,6 @@
-# Disallow non-null assertion in locations that may be confusing (`no-confusing-non-null-assertion`)
+# `no-confusing-non-null-assertion`
+
+Disallow non-null assertion in locations that may be confusing.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/no-confusing-void-expression.md b/packages/eslint-plugin/docs/rules/no-confusing-void-expression.md
@@ -1,4 +1,6 @@
-# Requires expressions of type void to appear in statement position (`no-confusing-void-expression`)
+# `no-confusing-void-expression`
+
+Requires expressions of type void to appear in statement position.
 
 Returning the results of an expression whose type is void can be misleading.
 Attempting to do so is likely a symptom of expecting a different return type from a function.

diff --git a/packages/eslint-plugin/docs/rules/no-dupe-class-members.md b/packages/eslint-plugin/docs/rules/no-dupe-class-members.md
@@ -1,4 +1,6 @@
-# Disallow duplicate class members (`no-dupe-class-members`)
+# `no-dupe-class-members`
+
+Disallow duplicate class members.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/no-duplicate-imports.md b/packages/eslint-plugin/docs/rules/no-duplicate-imports.md
@@ -1,4 +1,6 @@
-# Disallow duplicate imports (`no-duplicate-imports`)
+# `no-duplicate-imports`
+
+Disallow duplicate imports.
 
 ## Rule Details
 

diff --git a/packages/eslint-plugin/docs/rules/no-dynamic-delete.md b/packages/eslint-plugin/docs/rules/no-dynamic-delete.md
@@ -1,4 +1,6 @@
-# Disallow the delete operator with computed key expressions (`no-dynamic-delete`)
+# `no-dynamic-delete`
+
+Disallow the delete operator with computed key expressions.
 
 Deleting dynamically computed keys can be dangerous and in some cases not well optimized.
 

diff --git a/packages/eslint-plugin/docs/rules/no-empty-function.md b/packages/eslint-plugin/docs/rules/no-empty-function.md
@@ -1,4 +1,6 @@
-# Disallow empty functions (`no-empty-function`)
+# `no-empty-function`
+
+Disallow empty functions.
 
 ## Rule Details