docs: when not to use each rule

docs/rules/ban-observables.md

@@ -2,11 +2,16 @@
 
 <!-- end auto-generated rule header -->
 
-This rule can be configured so that developers can ban any observable creators they want to avoid in their project.
+It can sometimes be useful to ban specific `rxjs` imports.
+This rule can be configured to ban a list of specific `rxjs` imports developers want to avoid in their project.
+
+> [!TIP]
+> `ban-observables` only bans at the _import_ site. (In fact, it can ban anything imported from `rxjs`.)
+> See [`ban-operators`](./ban-operators.md) for banning operators at their _usage_.
 
 ## Options
 
-This rule accepts a single option which is an object the keys of which are the names of observable factory functions and the values are either booleans or strings containing the explanation for the ban.
+This rule accepts a single option which is an object the keys of which are the names of anything in `rxjs` and the values are either booleans or strings containing the explanation for the ban.
 
 The following configuration bans `partition` and `onErrorResumeNext`:
 
@@ -22,3 +27,16 @@ The following configuration bans `partition` and `onErrorResumeNext`:
   ]
 }
 ```
+
+## When Not To Use It
+
+If you have no need to ban importing anything from `rxjs`, you don't need this rule.
+
+## Related To
+
+- [`ban-operators`](./ban-operators.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/ban-observables.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/ban-observables.test.ts)

docs/rules/ban-operators.md

@@ -4,7 +4,10 @@
 
 <!-- end auto-generated rule header -->
 
-This rule can be configured so that developers can ban any operators they want to avoid in their project.
+This rule can be configured so that developers can ban `rxjs` operators they want to avoid in their project.
+
+> [!NOTE]
+> Operators outside of a `pipe` or not directly exported by `rxjs` are ignored.
 
 ## Options
 
@@ -23,3 +26,19 @@ The following configuration bans `partition` and `onErrorResumeNext`:
     }
   ]
 }
+```
+
+## When Not To Use It
+
+If you have no need to ban `rxjs` operators, you don't need this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Related To
+
+- [`ban-observables`](./ban-observables.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/ban-operators.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/ban-operators.test.ts)

docs/rules/finnish.md

@@ -68,6 +68,24 @@ The default (Angular-friendly) configuration looks like this:
 
 The properties in the options object are themselves optional; they do not all have to be specified.
 
+## When Not To Use It
+
+If you don't use Finnish notation in your project or don't care about enforcing Finnish notation in your project, you don't need this rule.
+However, keep in mind that inconsistent style can harm readability in a project;
+consider using [`no-finnish`](./no-finnish.md) to ban Finnish notation if you don't use it in your project.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
 ## Further reading
 
 - [Observables and Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b)
+
+## Related To
+
+- [`no-finnish`](./no-finnish.md)
+- [`suffix-subjects`](./suffix-subjects.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/finnish.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/finnish.test.ts)

docs/rules/just.md

@@ -6,6 +6,15 @@
 
 This rule enforces the use of `just` instead of `of`. Some other languages with Rx implementations use the former and this rule is for developers who have that preference.
 
+## When Not To Use It
+
+If you prefer `of` in your project, you will want to avoid this rule.
+
 ## Further reading
 
 - [Rename `of` to `just`](https://github.com/ReactiveX/rxjs/issues/3747)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/just.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/just.test.ts)

docs/rules/no-async-subscribe.md

@@ -36,7 +36,19 @@ of(42).pipe(
 ).subscribe(data2 => console.log(data2));
 ```
 
+## When Not To Use It
+
+If you don't care about avoiding `.subscribe(async...`, then you will not need this rule.
+However, keep in mind that features of observables like cancellation or retrying will not work, and race conditions may occur.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
 ## Further reading
 
 - [Why does this rule exist?](https://stackoverflow.com/q/71559135)
 - [Higher-order Observables](https://rxjs.dev/guide/higher-order-observables)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-async-subscribe.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-async-subscribe.test.ts)

docs/rules/no-connectable.md

@@ -4,4 +4,30 @@
 
 <!-- end auto-generated rule header -->
 
-This rule prevents the use of connectable observables.
+This rule prevents the use of operators that return connectable observables.
+
+> [!NOTE]
+> All operators banned by this rule are also deprecated by RxJS,
+> so this rule may be removed in a future major version.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+import { of, publish } from "rxjs";
+
+const result = of(42).pipe(publish());
+```
+
+## When Not To Use It
+
+If you use operators that return connectable observables in your project, you may not need this rule.
+Or you may rely on RxJS's deprecation of those operators and don't need to double-flag the operators as banned.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-connectable.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-connectable.test.ts)

docs/rules/no-create.md

@@ -29,3 +29,15 @@ const answers = new Observable<number>(subscriber => {
   subscriber.complete();
 });
 ```
+
+## When Not To Use It
+
+If you rely on RxJS's deprecation of `Observable.create` and don't need to double-flag usage,
+then you don't need this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-create.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-create.test.ts)

docs/rules/no-cyclic-action.md

@@ -72,3 +72,17 @@ This rule accepts a single option which is an object with an `observable` proper
   ]
 }
 ```
+
+## When Not To Use It
+
+If you don't use a library with effects and epics (e.g. NgRx or redux-observable),
+then you don't need this rule.
+Alternatively, if you use NgRx's own [`avoid-cyclic-effects`](https://ngrx.io/guide/eslint-plugin/rules/avoid-cyclic-effects) rule,
+then you don't need this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-cyclic-action.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-cyclic-action.test.ts)

docs/rules/no-explicit-generics.md

@@ -20,6 +20,13 @@ import { BehaviorSubject } from "rxjs";
 const subject = new BehaviorSubject(42);
 ```
 
-## Known problems
+## When Not To Use It
+
+This rule has known problems in the latest release:
 
 - ([#77](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/issues/77)) Type unions cause false positives e.g. `new BehaviorSubject<number | null>(null)` will be incorrectly caught by this rule.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-explicit-generics.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-explicit-generics.test.ts)

docs/rules/no-exposed-subjects.md

@@ -23,10 +23,13 @@ Examples of **correct** code for this rule:
 
 ```ts
 import { Subject } from "rxjs";
+
 class Answers {
-  private _answers: Subject<string>;
-  get answers() {
-    return this._answers.asObservable();
+  private answersSubject$ = new Subject<string>();
+  public answers$ = this.answersSubject$.asObservable();
+
+  public nextAnswer(a: string) {
+    this.answersSubject$.next(a);
   }
 }
 ```
@@ -51,3 +54,15 @@ This rule accepts a single option which is an object with an `allowProtected` pr
   ]
 }
 ```
+
+## When Not To Use It
+
+If you don't care about encapsulating subjects in your project, then you don't need this rule.
+However, be aware that anyone can call `next()` or `complete()` on the exposed subject, which may cause bugs or less readable code.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-exposed-subjects.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-exposed-subjects.test.ts)

docs/rules/no-finnish.md

@@ -20,6 +20,23 @@ Examples of **correct** code for this rule:
 const answers = of(42, 54);
 ```
 
+## When Not To Use It
+
+If you use Finnish notation in your project, you should avoid this rule.
+Or if you don't care if Finnish notation is used in your project, then you don't need this rule.
+However, keep in mind that inconsistent style can harm readability in a project.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
 ## Further reading
 
 - [Observables and Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b)
+
+## Related To
+
+- [`finnish`](./finnish.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-finnish.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-finnish.test.ts)

docs/rules/no-floating-observables.md

@@ -19,7 +19,7 @@ This rule will report observable-valued statements that are not treated in one o
 
 > [!TIP]
 > `no-floating-observables` only detects apparently unhandled observable _statements_.
-> See [`no-misused-observables`](./no-misused-observables.md) for detecting code that provides observables to _logical_ locations
+> See [`no-misused-observables`](./no-misused-observables.md) for detecting code that provides observables to _logical_ locations.
 
 ## Rule details
 
@@ -46,3 +46,23 @@ const answers = of(42, 54);
 | `ignoreVoid` | Whether to ignore `void` expressions. | Boolean | `true`  |
 
 <!-- end auto-generated rule options list -->
+
+## When Not To Use It
+
+Like `@typescript-eslint/no-floating-promises`,
+this rule can be difficult to enable on large existing projects that set up many floating observables.
+Alternatively, if you're not worried about ignored errors or unhandled cold observables,
+then in some cases it may be safe to not use this rule.
+You might consider using `void`s and/or ESLint disable comments for those specific situations
+instead of completely disabling this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Related To
+
+- [`no-misused-observables`](./no-misused-observables.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-floating-observables.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-floating-observables.test.ts)

docs/rules/no-ignored-default-value.md

@@ -29,3 +29,15 @@ const sub = new Subject();
 const result = firstValueFrom(sub, { defaultValue: null });
 sub.complete();
 ```
+
+## When Not To Use It
+
+If you intentionally want `EmptyError` rejections when the observable completes, then you may not need this rule.
+You might consider using ESLint disable comments for specific situations instead of completely disabling this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-default-value.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-default-value.test.ts)

docs/rules/no-ignored-error.md

@@ -37,3 +37,17 @@ source.subscribe({
   error: (error) => console.error(error)
 });
 ```
+
+## When Not To Use It
+
+If you're not worried about ignored errors, then in some cases it may be safe to not use this rule.
+Or if you use operators like `catchError` to handle all errors, then in some cases it may be safe to not use this rule.
+You might consider using ESLint disable comments for those specific situations
+instead of completely disabling this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-error.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-error.test.ts)

docs/rules/no-ignored-notifier.md

@@ -8,6 +8,10 @@
 
 This rule effects failures if the notifier passed to a `repeatWhen` or `retryWhen` callback is not used.
 
+> [!NOTE]
+> Both `repeatWhen` and `retryWhen` are deprecated by RxJS,
+> so this rule may be removed in a future major version.
+
 ## Rule details
 
 Examples of **incorrect** code for this rule:
@@ -30,3 +34,14 @@ const repeating = source.pipe(
   repeatWhen(notifications => notifications.pipe(take(3)))
 );
 ```
+
+## When Not To Use It
+
+If you don't use `repeatWhen` or `retryWhen` in your project, then you don't need this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-notifier.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-notifier.test.ts)

docs/rules/no-ignored-replay-buffer.md

@@ -36,3 +36,12 @@ const subject = new ReplaySubject<number>(Infinity);
 import { of, shareReplay } from "rxjs";
 of(42).pipe(shareReplay({ refCount: true, bufferSize: 1 }));
 ```
+
+## When Not To Use It
+
+If you don't care about implicitly defaulting to `Infinity` in your replay buffers, then you don't need this rule.
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-replay-buffer.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-replay-buffer.test.ts)

docs/rules/no-ignored-subscribe.md

@@ -26,3 +26,21 @@ import { of } from "rxjs";
 
 of(42, 54).subscribe((value) => console.log(value));
 ```
+
+## When Not To Use It
+
+If you don't care about errors or output of some observables in your project, you may not need this rule.
+Alternatively, you may require all logic to go in the `pipe` section of your observables.
+In that case, you should not use this rule and should enable [`no-subscribe-handlers`](./no-subscribe-handlers.md) instead,
+which is the opposite of this rule.
+
+Type checked lint rules are more powerful than traditional lint rules, but also require configuring type checked linting.
+
+## Related To
+
+- [`no-subscribe-handlers`](./no-subscribe-handlers.md)
+
+## Resources
+
+- [Rule source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/src/rules/no-ignored-subscribe.ts)
+- [Test source](https://github.com/JasonWeinzierl/eslint-plugin-rxjs-x/blob/main/tests/rules/no-ignored-subscribe.test.ts)