Improve descriptions of the *map operators

[deanrad]

The documentation of the timing operators mergeMap, concatMap, switchMap and exhaustMap is confusing. I've never heard that descriptions like these are illuminating:

Projects each source value to an Observable which is merged in the output Observable, emitting values only from the most recently projected Observable.

Everyone I know learns the operators from secondary sources - the docs could be improved to address that (the current descriptions are 5 years old).

I suspect the confusion is partly because the descriptions focus only on the emitted values, neglecting to mention the subscriptions used to control those values. It seems more descriptive of what's going on to include the Subscriptions, and to talk about their concurrency - an important factor in choosing them..

Objective: Update the description of each timing operator to reflect what they do more plainly.

Here are the proposed edits, I'd love to get other input or votes on this.

Note: - A comment that could be included in each - is that after piping through one of these operators, the resulting Observable immediately emits when any of its subscriptions does.

switchMap

The description of switchMap in terms of subscriptions could be:

Subscribes to each Observable mapped from each source value, maintaining only one active subscription at a time. If the subscription to the previous Observable has not completed, it is unsubscribed prior to the new Observable being subscribed.

concatMap

The description of concatMap in terms of subscriptions could be:

Subscribes to each Observable mapped from each source value, maintaining only one active subscription at a time. If the subscription for the previous source value has not completed, its successful completion is awaited prior to the new Observable being subscribed.

mergeMap

The description of mergeMap in terms of subscriptions could be:

Subscribes to each Observable mapped from each source value, with no concurrency limit. Each new subscription is made immediately, without regard to whether a subscription for the previous Observable has completed.

exhaustMap

The description of exhaustMap in terms of subscriptions could be:

Subscribes to an Observable mapped from each source value, maintaining only one active subscription at a time, only if there is no active subscription to a previous Observable.

---

There is actually a useful table showing the relation of these operators (and suggesting that a 5th, toggling operator could exist!). Im including that, as I've used it in explanations before and it may have a place in the docs as well.

operator	existing	new	when
mergeMap	lives	subscribed	immediately
concatMap	lives	subscribed	upon completion of previous
exhaustMap	lives	not subscribed
switchMap	unsubscribed	subscribed
toggleMap?	unsubscribed	not subscribed

[deanrad]

Do people look at discussions? I know we were suggested to start here, but the 🦗 ...