docs: Improve README and JSDocs

README.md

@@ -37,14 +37,17 @@ Main features
 
 - [Installation](#installation)
 - [API](#api)
-  - [connectObservable](#connectObservable)
-  - [connectFactoryObservable](#connectFactoryObservable)
-  - [shareLatest](#shareLatest)
-  - [SUSPENSE](#SUSPENSE)
-  - [suspend](#suspend)
-  - [suspended](#suspended)
-  - [switchMapSuspended](#switchMapSuspended)
-  - [createInput](#createInput)
+  - Core
+    - [connectObservable](#connectObservable)
+    - [connectFactoryObservable](#connectFactoryObservable)
+    - [shareLatest](#shareLatest)
+  - React Suspense Support
+    - [SUSPENSE](#SUSPENSE)
+    - [suspend](#suspend)
+    - [suspended](#suspended)
+    - [switchMapSuspended](#switchMapSuspended)
+  - Utils
+    - [createInput](#createInput)
 - [Examples](#examples)
 
 
@@ -62,12 +65,17 @@ const [useCounter, sharedCounter$] = connectObservable(
   )
 )
 ```
-Returns a hook that provides the latest update of the accepted observable, and the
-underlying enhanced observable, which shares the subscription to all of its subscribers,
-and always emits the latest value when subscribing to it.
+Accepts: An Observable.
 
-The shared subscription is closed as soon as there are no subscribers to that
-observable.
+Returns `[1, 2]`
+
+1. A React Hook that yields the latest emitted value of the observable. If the
+Observable doesn't synchronously emit a value upon the first subscription, then
+the hook will leverage React Suspense while it's waiting for the first value.
+
+2. A `sharedLatest` version of the observable that does not complete. It can be
+used for composing other streams that depend on it. The shared subscription is
+closed as soon as there are no subscribers to that observable.
 
 ### connectFactoryObservable
 ```tsx
@@ -86,16 +94,18 @@ const Story: React.FC<{id: number}> = ({id}) => {
   )
 }
 ```
-Accepts:
-A factory function that returns an Observable.
+Accepts: A factory function that returns an Observable.
 
 Returns `[1, 2]`
 
 1. A React Hook function with the same parameters as the factory function. This hook
 will yield the latest update from the observable returned from the factory function.
+If the Observable doesn't synchronously emit a value upon the first subscription, then
+the hook will leverage React Suspense while it's waiting for the first value.
 
 2. A `sharedLatest` version of the observable returned by the factory function that
 does not complete. It can be used for composing other streams that depend on it.
+The shared subscription is closed as soon as there are no subscribers to that observable.
 
 ### shareLatest
 ```ts
@@ -133,7 +143,7 @@ const story$ = selectedStoryId$.pipe(
 ```
 
 This is a special symbol that can be emitted from our observables to let the react hook
-know that there is a value on its way, and that we want to leverage React Suspense API
+know that there is a value on its way, and that we want to leverage React Suspense
 while we are waiting for that value.
 
 ### suspend

src/connectFactoryObservable.ts

@@ -14,13 +14,18 @@ import { SUSPENSE } from "./SUSPENSE"
  *  the factory function.
  * 2. A shared replayable version of the observable generated by the factory
  *  function that can be used for composing other streams that depend on it.
- *  This observable is disposed when its refCount goes down to zero.
+ *  The shared subscription is closed as soon as there are no subscribers to
+ *  that observable.
  *
  * @param getObservable Factory of observables. The arguments of this function
  *  will be the ones used in the hook.
  * @param unsubscribeGraceTime (= 200): Amount of time in ms that the shared
- *        observable should wait before unsubscribing from the source observable
- *        when there are no new subscribers.
+ *  observable should wait before unsubscribing from the source observable when
+ *  there are no new subscribers.
+ *
+ * @remarks If the Observable doesn't synchronously emit a value upon the first
+ * subscription, then the hook will leverage React Suspense while it's waiting
+ * for the first value.
  */
 export function connectFactoryObservable<
   A extends (number | string | boolean | null)[],

src/connectObservable.ts

@@ -4,17 +4,22 @@ import reactEnhancer from "./internal/react-enhancer"
 import { useObservable } from "./internal/useObservable"
 
 /**
- * Returns a hook that provides the latest update of the accepted observable,
- * and the underlying enhanced observable, which shares the subscription to all
- * of its subscribers, and always emits the latest value when subscribing to it.
+ * Accepts: An Observable.
  *
- * The shared subscription is closed as soon as there are no subscribers to that
- * observable.
+ * Returns [1, 2]
+ * 1. A React Hook that yields the latest emitted value of the observable
+ * 2. A `sharedLatest` version of the observable that does not complete. It can
+ * be used for composing other streams that depend on it. The shared subscription
+ * is closed as soon as there are no subscribers to that observable.
  *
  * @param observable Source observable to be used by the hook.
  * @param unsubscribeGraceTime (= 200): Amount of time in ms that the shared
- *        observable should wait before unsubscribing from the source observable
- *        when there are no new subscribers.
+ * observable should wait before unsubscribing from the source observable when
+ * there are no new subscribers.
+ *
+ * @remarks If the Observable doesn't synchronously emit a value upon the first
+ * subscription, then the hook will leverage React Suspense while it's waiting
+ * for the first value.
  */
 export function connectObservable<T>(
   observable: Observable<T>,