docs(no-misused-observables): examples & description

Author: JasonWeinzierl

docs/rules/no-misused-observables.md

@@ -6,14 +6,63 @@
 
 <!-- end auto-generated rule header -->
 
+This rule forbids providing observables to logical locations where the TypeScript compiler allows them but they are not handled properly.
+These situations can often arise due to a misunderstanding of the way observables are handled.
+
+> [!TIP]
+> `no-misused-observables` only detects code that provides observables to incorrect _logical_ locations.
+> See [`no-floating-observables`](./no-floating-observables.md) for detecting unhandled observable _statements_.
+
+This rule is like [no-misused-promises](https://typescript-eslint.io/rules/no-misused-promises) but for Observables.
+
+> [!NOTE]
+> Unlike `@typescript-eslint/no-misused-promises`, this rule does not check conditionals like `if` statements.
+> Use `@typescript-eslint/no-unnecessary-condition` for linting those situations.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+import { of } from "rxjs";
+
+[1, 2, 3].forEach(i => of(i));
+
+interface MySyncInterface {
+    foo(): void;
+}
+class MyRxClass implements MySyncInterface {
+    foo(): Observable<number> {
+        return of(42);
+    }
+}
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+import { of } from "rxjs";
+
+[1, 2, 3].map(i => of(i));
+
+interface MyRxInterface {
+    foo(): Observable<number>;
+}
+class MyRxClass implements MyRxInterface {
+    foo(): Observable<number> {
+        return of(42);
+    }
+}
+```
+
 ## Options
 
 <!-- WARNING: not auto-generated! -->
 
-| Name               | Description                                                                                                                              | Type    | Default |
-| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------ | :------ |
-| `checksSpreads`    | Disallow `...` spreading an Observable.                                                                                                  | Boolean | `true`  |
-| `checksVoidReturn` | Disallow returning an Observable from a function typed as returning `void`.                                                              | Object  | `true`  |
+| Name               | Description                                                                 | Type    | Default |
+| :----------------- | :-------------------------------------------------------------------------- | :------ | :------ |
+| `checksSpreads`    | Disallow `...` spreading an Observable.                                     | Boolean | `true`  |
+| `checksVoidReturn` | Disallow returning an Observable from a function typed as returning `void`. | Object  | `true`  |
 
 ### `checksVoidReturn`
 
@@ -27,3 +76,7 @@ You can disable selective parts of the `checksVoidReturn` option. The following
 | `properties`       | Disallow providing an Observable-returning function where a function that returns `void` is expected by a property.                      | Boolean | `true`  |
 | `returns`          | Disallow returning an Observable-returning function where a function that returns `void` is expected.                                    | Boolean | `true`  |
 | `variables`        | Disallow assigning or declaring an Observable-returning function where a function that returns `void` is expected.                       | Boolean | `true`  |
+
+## Further reading
+
+- [TypeScript void function assignability](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-functions-returning-non-void-assignable-to-function-returning-void)