Skip to content

Commit 37f34f4

Browse files
JoshuaKGoldbergJoshuaKGoldberg
authored
docs: add 'When Not To Use It' or an intentional omission notice on all rules (#7447)
* docs: enforce 'When Not To Use It' on all rules * Responded to immediate feedback * Filled them all in and updated test * Remove .nx shenanigans * Mentioned areas of unsafe code too
1 parent 96abf18 commit 37f34f4

89 files changed

Lines changed: 385 additions & 80 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@
119119
"serializers",
120120
"Sourcegraph",
121121
"stringification",
122+
"stringifying",
122123
"stringly",
123124
"superset",
124125
"thenables",

‎packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,4 +90,10 @@ export function foo(sn: string | number): void;
9090

9191
## When Not To Use It
9292

93-
If you don't care about the general structure of the code, then you will not need this rule.
93+
It can sometimes be useful to place overload signatures alongside other meaningful parts of a type.
94+
For example, if each of a function's overloads corresponds to a different property, you might wish to put each overloads next to its corresponding property.
95+
You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
96+
97+
## Related To
98+
99+
- [`unified-signatures`](./unified-signatures.md)

‎packages/eslint-plugin/docs/rules/array-type.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,3 +101,11 @@ This matrix lists all possible option combinations and their expected results fo
101101
| `generic` | `array` | `Array<number>` | `Array<Foo & Bar>` | `readonly number[]` | `readonly (Foo & Bar)[]` |
102102
| `generic` | `array-simple` | `Array<number>` | `Array<Foo & Bar>` | `readonly number[]` | `ReadonlyArray<Foo & Bar>` |
103103
| `generic` | `generic` | `Array<number>` | `Array<Foo & Bar>` | `ReadonlyArray<number>` | `ReadonlyArray<Foo & Bar>` |
104+
105+
## When Not To Use It
106+
107+
This rule is purely a stylistic rule for maintaining consistency in your project.
108+
You can turn it off if you don't want to keep a consistent style for array types.
109+
110+
However, keep in mind that inconsistent style can harm readability in a project.
111+
We recommend picking a single option for this rule that works best for your project.

‎packages/eslint-plugin/docs/rules/await-thenable.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,6 @@ await createValue();
3737
## When Not To Use It
3838

3939
If you want to allow code to `await` non-Promise values.
40-
This is generally not preferred, but can sometimes be useful for visual consistency.
40+
For example, if your framework is in transition from one style of asynchronous code to another, it may be useful to include `await`s unnecessarily.
41+
This is generally not preferred but can sometimes be useful for visual consistency.
42+
You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.

‎packages/eslint-plugin/docs/rules/ban-ts-comment.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,8 @@ if (false) {
143143

144144
## When Not To Use It
145145

146-
If you want to use all of the TypeScript directives.
146+
If your project or its dependencies were not architected with strong type safety in mind, it can be difficult to always adhere to proper TypeScript semantics.
147+
You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
147148

148149
## Further Reading
149150

‎packages/eslint-plugin/docs/rules/ban-tslint-comment.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,4 +36,4 @@ someCode(); // This is a comment that just happens to mention tslint
3636

3737
## When Not To Use It
3838

39-
If you are still using TSLint.
39+
If you are still using TSLint alongside ESLint.

‎packages/eslint-plugin/docs/rules/ban-types.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,8 @@ Example configuration:
125125
]
126126
}
127127
```
128+
129+
## When Not To Use It
130+
131+
If your project is a rare one that intentionally deals with the class equivalents of primitives, it might not be worthwhile to enable the default `ban-types` options.
132+
You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.

‎packages/eslint-plugin/docs/rules/class-literal-property-style.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,4 @@ class Mx {
102102

103103
## When Not To Use It
104104

105-
When you have no strong preference, or do not wish to enforce a particular style
106-
for how literal values are exposed by your classes.
105+
When you have no strong preference, or do not wish to enforce a particular style for how literal values are exposed by your classes.

‎packages/eslint-plugin/docs/rules/class-methods-use-this.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,8 @@ class X implements Y {
8989
property = () => {};
9090
}
9191
```
92+
93+
## When Not To Use It
94+
95+
If your project dynamically changes `this` scopes around in a way TypeScript has difficulties modeling, this rule may not be viable to use.
96+
You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.

‎packages/eslint-plugin/docs/rules/consistent-generic-constructors.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,6 @@ const set: Set<string> = new Set<string>();
7171
## When Not To Use It
7272

7373
You can turn this rule off if you don't want to enforce one kind of generic constructor style over the other.
74+
75+
However, keep in mind that inconsistent style can harm readability in a project.
76+
We recommend picking a single option for this rule that works best for your project.

0 commit comments

Comments
 (0)