typescript-eslint · JoshuaKGoldberg · Oct 4, 2022 · Sep 28, 2022 · Sep 28, 2022 · Sep 30, 2022
diff --git a/packages/eslint-plugin/docs/rules/TEMPLATE.md b/packages/eslint-plugin/docs/rules/TEMPLATE.md
@@ -2,7 +2,7 @@
 >
 > See **https://typescript-eslint.io/rules/your-rule-name** for documentation.
 
-## Rule Details
+## Examples
 
 To fill out: tell us more about this rule.
 

diff --git a/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md b/packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md
@@ -1,16 +1,16 @@
 ---
-description: 'Require that member overloads be consecutive.'
+description: 'Require that function overload signatures be consecutive.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/adjacent-overload-signatures** for documentation.
 
-Grouping overloaded members together can improve readability of the code.
+Function overload signatures represent multiple ways a function can be called, potentially with different return types.
+It's typical for an interface or type alias describing a function to place all overload signatures next to each other.
+If Signatures placed elsewhere in the type are easier to be missed by future developers reading the code.
 
-## Rule Details
-
-This rule aims to standardize the way overloaded members are organized.
+## Examples
 
 <!--tabs-->
 

diff --git a/packages/eslint-plugin/docs/rules/array-type.md b/packages/eslint-plugin/docs/rules/array-type.md
@@ -1,16 +1,14 @@
 ---
-description: 'Require using either `T[]` or `Array<T>` for arrays.'
+description: 'Require consistently using either `T[]` or `Array<T>` for arrays.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/array-type** for documentation.
 
-Using the same style for array definitions across your codebase makes it easier for your developers to read and understand the types.
-
-## Rule Details
-
-This rule aims to standardize usage of array types within your codebase.
+TypeScript provides two equivalent ways to define an array type: `T[]` and `Array<T>`.
+The two styles are functionally equivalent.
+Using the same style consistently across your codebase makes it easier for developers to read and understand array types.
 
 ## Options
 

diff --git a/packages/eslint-plugin/docs/rules/await-thenable.md b/packages/eslint-plugin/docs/rules/await-thenable.md
@@ -6,12 +6,13 @@ description: 'Disallow awaiting a value that is not a Thenable.'
 >
 > See **https://typescript-eslint.io/rules/await-thenable** for documentation.
 
-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.
+A "Thenable" value is an object with has a `then` method, such as a Promise.
+The `await` keyword is generally used to retrieve the result of calling a Thenable's `then` method.
 
-## Rule Details
+If the `await` keyword is used on a value that is not a Thenable, the value is directly resolved immediately.
+While doing so is valid JavaScript, it is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
 
-Examples of code for this rule:
+## Examples
 
 <!--tabs-->
 

diff --git a/packages/eslint-plugin/docs/rules/ban-ts-comment.md b/packages/eslint-plugin/docs/rules/ban-ts-comment.md
@@ -1,13 +1,14 @@
 ---
-description: 'Disallow `@ts-<directive>` comments or require descriptions after directive.'
+description: 'Disallow `@ts-<directive>` comments or require descriptions after directives.'
 ---
 
 > 🛑 This file is source code, not the primary documentation location! 🛑
 >
 > See **https://typescript-eslint.io/rules/ban-ts-comment** for documentation.
 
 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.
+Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall.
+Instead, it's generally better to correct the types of code, to make directives unnecessary.
 
 The directive comments supported by TypeScript are:
 
@@ -18,8 +19,6 @@ The directive comments supported by TypeScript are:
 // @ts-check
 ```
 
-## Rule Details
-
 This rule lets you set which directive comments you want to allow in your codebase.
 
 ## Options

diff --git a/packages/eslint-plugin/docs/rules/ban-tslint-comment.md b/packages/eslint-plugin/docs/rules/ban-tslint-comment.md
@@ -8,9 +8,9 @@ description: 'Disallow `// tslint:<rule-flag>` comments.'
 
 Useful when migrating from TSLint to ESLint. Once TSLint has been removed, this rule helps locate TSLint annotations (e.g. `// tslint:disable`).
 
-## Rule Details
+> See the [TSLint rule flags docs](https://palantir.github.io/tslint/usage/rule-flags) for reference.
 
-All TSLint [rule flags](https://palantir.github.io/tslint/usage/rule-flags/)
+## Examples
 
 <!--tabs-->
 

diff --git a/packages/eslint-plugin/docs/rules/ban-types.md b/packages/eslint-plugin/docs/rules/ban-types.md
@@ -9,11 +9,11 @@ description: 'Disallow certain types.'
 Some built-in types have aliases, while some types are considered dangerous or harmful.
 It's often a good idea to ban certain types to help with consistency and safety.
 
-## Rule Details
-
 This rule bans specific types and can suggest alternatives.
 Note that it does not ban the corresponding runtime objects from being used.
 
+## Examples
+
 Examples of code with the default options:
 
 <!--tabs-->

diff --git a/packages/eslint-plugin/docs/rules/brace-style.md b/packages/eslint-plugin/docs/rules/brace-style.md
@@ -6,7 +6,7 @@ description: 'Enforce consistent brace style for blocks.'
 >
 > See **https://typescript-eslint.io/rules/brace-style** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/brace-style`](https://eslint.org/docs/rules/brace-style) rule.
 It adds support for `enum`, `interface`, `namespace` and `module` declarations.
diff --git a/packages/eslint-plugin/docs/rules/class-literal-property-style.md b/packages/eslint-plugin/docs/rules/class-literal-property-style.md
@@ -6,14 +6,14 @@ description: 'Enforce that literals on classes are exposed in a consistent style
 >
 > See **https://typescript-eslint.io/rules/class-literal-property-style** for documentation.
 
-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.
-
-## Options
+Some TypeScript applications 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.
 
 This rule aims to ensure that literals exposed by classes are done so consistently, in one of the two style described above.
 By default this rule prefers the `fields` style as it means JS doesn't have to setup & teardown a function closure.
 
+## Options
+
 :::note
 
 This rule only checks for constant _literal_ values (string, template string, number, bigint, boolean, regexp, null). It does not check objects or arrays, because a readonly field behaves differently to a getter in those cases. It also does not check functions, as it is a common pattern to use readonly fields with arrow function values as auto-bound methods.

diff --git a/packages/eslint-plugin/docs/rules/comma-dangle.md b/packages/eslint-plugin/docs/rules/comma-dangle.md
@@ -6,7 +6,7 @@ description: 'Require or disallow trailing commas.'
 >
 > See **https://typescript-eslint.io/rules/comma-dangle** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/comma-dangle`](https://eslint.org/docs/rules/comma-dangle) rule.
 It adds support for TypeScript syntax.

diff --git a/packages/eslint-plugin/docs/rules/comma-spacing.md b/packages/eslint-plugin/docs/rules/comma-spacing.md
@@ -6,7 +6,7 @@ description: 'Enforce consistent spacing before and after commas.'
 >
 > See **https://typescript-eslint.io/rules/comma-spacing** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/comma-spacing`](https://eslint.org/docs/rules/comma-spacing) rule.
 It adds support for trailing comma in a types parameters list.
diff --git a/packages/eslint-plugin/docs/rules/consistent-generic-constructors.md b/packages/eslint-plugin/docs/rules/consistent-generic-constructors.md
@@ -17,10 +17,10 @@ const map = new Map<string, number>();
 ```
 
 This rule ensures that type arguments appear consistently on one side of the declaration.
+Keeping to one side consistently improve code readability.
 
-## Rule Details
-
-The rule never reports when there are type parameters on both sides, or neither sides of the declaration. It also doesn't report if the names of the type annotation and the constructor don't match.
+> The rule never reports when there are type parameters on both sides, or neither sides of the declaration.
+> It also doesn't report if the names of the type annotation and the constructor don't match.
 
 ## Options
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.md b/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.md
@@ -20,9 +20,7 @@ type Foo = {
 type Foo = Record<string, unknown>;
 ```
 
-## Rule Details
-
-This rule enforces a consistent way to define records.
+Keeping to one declaration form consistently improve code readability.
 
 ## Options
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-assertions.md b/packages/eslint-plugin/docs/rules/consistent-type-assertions.md
@@ -6,15 +6,22 @@ description: 'Enforce consistent usage of type assertions.'
 >
 > See **https://typescript-eslint.io/rules/consistent-type-assertions** for documentation.
 
-## Rule Details
+TypeScript provides two syntaxes for "type assertions":
 
-This rule aims to standardize the use of type assertion style across the codebase.
+- Angle brackets: `<Type>value`
+- As: `value as Type`
 
-Type assertions are also commonly referred as "type casting" in TypeScript (even though it is technically slightly different to what is understood by type casting in other languages), so you can think of type assertions and type casting referring to the same thing. It is essentially you saying to the TypeScript compiler, "in this case, I know better than you!".
+This rule aims to standardize the use of type assertion style across the codebase.
+Keeping to one syntax consistently helps with code readability.
 
-In addition to ensuring that type assertions are written in a consistent way, this rule also helps make your codebase more type-safe.
+:::note
+Type assertions are also commonly referred as "type casting" in TypeScript.
+However, that term is technically slightly different to what is understood by type casting in other languages.
+Type assertions are a way to say to the TypeScript compiler, _"I know better than you, it's actually this different type!"_.
+:::
 
-[`const` assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) are always allowed by this rule. Examples of them include `let x = "hello" as const;` and `let x = <const>"hello";`.
+[`const` assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) are always allowed by this rule.
+Examples of them include `let x = "hello" as const;` and `let x = <const>"hello";`.
 
 ## Options
 

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-definitions.md b/packages/eslint-plugin/docs/rules/consistent-type-definitions.md
@@ -6,7 +6,7 @@ description: 'Enforce type definitions to consistently use either `interface` or
 >
 > See **https://typescript-eslint.io/rules/consistent-type-definitions** for documentation.
 
-There are two ways to define a type.
+TypeScript provides two common ways to define an object type: `interface` and `type`.
 
 ```ts
 // type alias
@@ -22,6 +22,9 @@ interface T2 {
 }
 ```
 
+The two are generally very similar, and can often be used interchangeably.
+Using the same type declaration style consistently helps with code readability.
+
 ## Options
 
 - `"interface"` _(default)_: enforce using `interface`s for object type definitions.

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-exports.md b/packages/eslint-plugin/docs/rules/consistent-type-exports.md
@@ -6,14 +6,10 @@ description: 'Enforce consistent usage of type exports.'
 >
 > See **https://typescript-eslint.io/rules/consistent-type-exports** for documentation.
 
-Type-only exports allow you to specify that 1 or more named exports are exported as type-only. This allows
-transpilers to drop exports without knowing the types of the dependencies.
+TypeScript allows specifying a `type` keyword on exports to indicate that the export exists only in the type system, not at runtime.
+This allows transpilers to drop exports without knowing the types of the dependencies.
 
-## Rule Details
-
-This rule aims to standardize the use of type exports style.
-
-Given a class `Button`, and an interface `ButtonProps`, examples of code:
+## Examples
 
 <!--tabs-->
 
@@ -25,9 +21,7 @@ interface ButtonProps {
 }
 
 class Button implements ButtonProps {
-  onClick() {
-    console.log('button!');
-  }
+  onClick = () => console.log('button!');
 }
 
 export { Button, ButtonProps };
@@ -39,11 +33,11 @@ export { Button, ButtonProps };
 interface ButtonProps {
   onClick: () => void;
 }
+
 class Button implements ButtonProps {
-  onClick() {
-    console.log('button!');
-  }
+  onClick = () => console.log('button!');
 }
+
 export { Button };
 export type { ButtonProps };
 ```

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.md b/packages/eslint-plugin/docs/rules/consistent-type-imports.md
@@ -6,11 +6,8 @@ description: 'Enforce consistent usage of type imports.'
 >
 > See **https://typescript-eslint.io/rules/consistent-type-imports** for documentation.
 
-Type-only imports allow you to specify that an import can only be used in a type location, allowing certain optimizations within compilers.
-
-## Rule Details
-
-This rule aims to standardize the use of type imports style.
+TypeScript allows specifying a `type` keyword on imports to indicate that the export exists only in the type system, not at runtime.
+This allows transpilers to drop imports without knowing the types of the dependencies.
 
 ## Options
 

diff --git a/packages/eslint-plugin/docs/rules/default-param-last.md b/packages/eslint-plugin/docs/rules/default-param-last.md
@@ -6,7 +6,7 @@ description: 'Enforce default parameters to be last.'
 >
 > See **https://typescript-eslint.io/rules/default-param-last** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/default-param-last`](https://eslint.org/docs/rules/default-param-last) rule.
 It adds support for optional parameters.

diff --git a/packages/eslint-plugin/docs/rules/dot-notation.md b/packages/eslint-plugin/docs/rules/dot-notation.md
@@ -6,7 +6,7 @@ description: 'Enforce dot notation whenever possible.'
 >
 > See **https://typescript-eslint.io/rules/dot-notation** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/dot-notation`](https://eslint.org/docs/rules/dot-notation) rule.
 It adds:

diff --git a/packages/eslint-plugin/docs/rules/explicit-function-return-type.md b/packages/eslint-plugin/docs/rules/explicit-function-return-type.md
@@ -6,14 +6,15 @@ description: 'Require explicit return types on functions and class methods.'
 >
 > See **https://typescript-eslint.io/rules/explicit-function-return-type** for documentation.
 
-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
-where there is no return value, that the calling code doesn't try to use the undefined value when it
-shouldn't.
+Functions in TypeScript often don't need to be given an explicit return type annotation.
+Leaving off the return type is less code to read or write and allows the compiler to infer it from the contents of the function.
 
-## Rule Details
+However, explicit return types do make it visually more clear what type is returned by a function.
+They can also speed up TypeScript type checking performance in large codebases with many large functions.
 
-This rule aims to ensure that the values returned from functions are of the expected type.
+This rule enforces that functions do have an explicit return type annotation.
+
+## Examples
 
 <!--tabs-->
 

diff --git a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.md
@@ -6,12 +6,16 @@ description: 'Require explicit accessibility modifiers on class properties and m
 >
 > See **https://typescript-eslint.io/rules/explicit-member-accessibility** for documentation.
 
-Leaving off accessibility modifier and making everything public can make
-your interface hard to use by others.
-If you make all internal pieces private or protected, your interface will
-be easier to use.
+TypeScript allows placing explicit `public`, `protected`, and `private` accessibility modifiers in front of class members.
+The modifiers exist solely in the type system and just server to describe who is allowed to access those members.
 
-## Rule Details
+Leaving off accessibility modifiers makes for less code to read and write.
+Members are `public` by default.
+
+However, adding in explicit accessibility modifiers can be helpful in codebases with many classes for enforcing proper privacy of members.
+Some developers also find it preferable for code readability to keep member publicity explicit.
+
+## Examples
 
 This rule aims to make code more readable and explicit about who can use
 which properties.
@@ -324,4 +328,4 @@ If you think defaulting to public is a good default, then you should consider us
 
 ## Further Reading
 
-- TypeScript [Accessibility Modifiers](https://www.typescriptlang.org/docs/handbook/classes.html#public-private-and-protected-modifiers)
+- TypeScript [Accessibility Modifiers Handbook Docs](https://www.typescriptlang.org/docs/handbook/2/classes.html#member-visibility)
diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md
@@ -7,10 +7,10 @@ description: "Require explicit return and argument types on exported functions'
 > See **https://typescript-eslint.io/rules/explicit-module-boundary-types** for documentation.
 
 Explicit types for function return values and arguments makes it clear to any calling code what is the module boundary's input and output.
+Adding explicit type annotations for those types can help improve code readability.
+It can also improve TypeScript type checking performance on larger codebases.
 
-## Rule Details
-
-This rule aims to ensure that the values returned from a module are of the expected type.
+## Examples
 
 <!--tabs-->
 

diff --git a/packages/eslint-plugin/docs/rules/func-call-spacing.md b/packages/eslint-plugin/docs/rules/func-call-spacing.md
@@ -6,7 +6,7 @@ description: 'Require or disallow spacing between function identifiers and their
 >
 > See **https://typescript-eslint.io/rules/func-call-spacing** for documentation.
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/func-call-spacing`](https://eslint.org/docs/rules/func-call-spacing) rule.
 It adds support for generic type parameters on function calls.
diff --git a/packages/eslint-plugin/docs/rules/indent.md b/packages/eslint-plugin/docs/rules/indent.md
@@ -14,7 +14,7 @@ Please read [Issue #1824: Problems with the indent rule](https://github.com/type
 
 :::
 
-## Rule Details
+## Examples
 
 This rule extends the base [`eslint/indent`](https://eslint.org/docs/rules/indent) rule.
 It adds support for TypeScript nodes.