docs: when not to use each rule (#91)

Adds useful documentation like typescript-eslint's **When Not To Use
It** section to each rule.

This also cleans up or expands on various existing rule documentation.
This also adds a **Resources** section to each rule linking to the rule
source and unit tests. This also tries to link related rules together in
a **Related To** section.

Resolves #67

Author: JasonWeinzierl

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)