docs(deprecations): remove jsdoc style from deprecation message

docs_app/content/guide/higher-order-observables.md

@@ -0,0 +1,28 @@
+# Higher-order Observables
+
+Observables most commonly emit ordinary values like strings and numbers, but surprisingly often, it is necessary to handle Observables *of* Observables, so-called higher-order Observables. For example, imagine you have an Observable emitting strings that are the URLs of files you want to fetch. The code might look like this:
+
+```ts
+const fileObservable = urlObservable.pipe(
+   map(url => http.get(url)),
+);
+```
+
+`http.get()` returns an Observable for each URL. Now you have an Observable *of* Observables, a higher-order Observable.
+
+But how do you work with a higher-order Observable? Typically, by _flattening_: by converting a higher-order Obser vable into an ordinary Observable. For example:
+
+```ts
+const fileObservable = urlObservable.pipe(
+   concatMap(url => http.get(url)),
+);
+```
+
+The Observable returned in the `concatMap` function is usually referred to as a so-called "inner" Observable, while in this context the `urlObservable` is the so-called "outer" Observable.
+
+The [`concatMap()`](/api/operators/concatMap) operator subscribes to each "inner" Observable, buffers all further emissions of the "outer" Observable, and copies all the emitted values until the inner Observable completes, and continues processing the values of the "outer Observable". All of the values are in that way concatenated.  Other useful flattening operators are
+
+* [`mergeMap()`](/api/operators/mergeMap) — subscribes to each inner Observable as it arrives, then emits each value as it arrives
+* [`switchMap()`](/api/operators/switchMap) — subscribes to the first inner Observable when it arrives, and emits each value as it arrives, but when the next inner Observable arrives, unsubscribes to the previous one, and subscribes to the new one.
+* [`exhaustMap()`](/api/operators/exhaustMap) — subscribes to the first inner Observable when it arrives, and emits each value as it arrives, discarding all newly arriving inner Observables until that first one completes, then waits for the next inner Observable.
+

src/internal/observable/combineLatest.ts

@@ -44,19 +44,19 @@ export function combineLatest<O1 extends ObservableInput<any>, O2 extends Observ
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>, O5 extends ObservableInput<any>, O6 extends ObservableInput<any>, R>(v1: O1, v2: O2, v3: O3, v4: O4, v5: O5, v6: O6, resultSelector: (v1: ObservedValueOf<O1>, v2: ObservedValueOf<O2>, v3: ObservedValueOf<O3>, v4: ObservedValueOf<O4>, v5: ObservedValueOf<O5>, v6: ObservedValueOf<O6>) => R, scheduler?: SchedulerLike): Observable<R>;
 
 // With a scheduler (deprecated)
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>>(sources: [O1], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>>(sources: [O1, O2], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>>(sources: [O1, O2, O3], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>>(sources: [O1, O2, O3, O4], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>, O5 extends ObservableInput<any>>(sources: [O1, O2, O3, O4, O5], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>, ObservedValueOf<O5>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>, O5 extends ObservableInput<any>, O6 extends ObservableInput<any>>(sources: [O1, O2, O3, O4, O5, O6], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>, ObservedValueOf<O5>, ObservedValueOf<O6>]>;
-/** @deprecated The scheduler argument is deprecated, use {@link subscribeOn} and/or {@link observeOn}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use subscribeOn and/or observeOn. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O extends ObservableInput<any>>(sources: O[], scheduler: SchedulerLike): Observable<ObservedValueOf<O>[]>;
 
 // Best case

src/internal/observable/concat.ts

@@ -4,17 +4,17 @@ import { of } from './of';
 import { concatAll } from '../operators/concatAll';
 
 /* tslint:disable:max-line-length */
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>>(v1: O1, scheduler: SchedulerLike): Observable<ObservedValueOf<O1>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>>(v1: O1, v2: O2, scheduler: SchedulerLike): Observable<ObservedValueOf<O1> | ObservedValueOf<O2>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>>(v1: O1, v2: O2, v3: O3, scheduler: SchedulerLike): Observable<ObservedValueOf<O1> | ObservedValueOf<O2> | ObservedValueOf<O3>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>>(v1: O1, v2: O2, v3: O3, v4: O4, scheduler: SchedulerLike): Observable<ObservedValueOf<O1> | ObservedValueOf<O2> | ObservedValueOf<O3> | ObservedValueOf<O4>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>, O5 extends ObservableInput<any>>(v1: O1, v2: O2, v3: O3, v4: O4, v5: O5, scheduler: SchedulerLike): Observable<ObservedValueOf<O1> | ObservedValueOf<O2> | ObservedValueOf<O3> | ObservedValueOf<O4> | ObservedValueOf<O5>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link concatAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and concatAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function concat<O1 extends ObservableInput<any>, O2 extends ObservableInput<any>, O3 extends ObservableInput<any>, O4 extends ObservableInput<any>, O5 extends ObservableInput<any>, O6 extends ObservableInput<any>>(v1: O1, v2: O2, v3: O3, v4: O4, v5: O5, v6: O6, scheduler: SchedulerLike): Observable<ObservedValueOf<O1> | ObservedValueOf<O2> | ObservedValueOf<O3> | ObservedValueOf<O4> | ObservedValueOf<O5> | ObservedValueOf<O6>>;
 
 export function concat<A extends ObservableInput<any>[]>(...observables: A): Observable<ObservedValueUnionFromArray<A>>;

src/internal/observable/from.ts

@@ -4,7 +4,7 @@ import { ObservableInput, SchedulerLike, ObservedValueOf } from '../types';
 import { scheduled } from '../scheduled/scheduled';
 
 export function from<O extends ObservableInput<any>>(input: O): Observable<ObservedValueOf<O>>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function from<O extends ObservableInput<any>>(input: O, scheduler: SchedulerLike): Observable<ObservedValueOf<O>>;
 
 /**

src/internal/observable/merge.ts

@@ -5,29 +5,29 @@ import { mergeAll } from '../operators/mergeAll';
 import { fromArray } from './fromArray';
 
 /* tslint:disable:max-line-length */
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T>(v1: ObservableInput<T>, scheduler: SchedulerLike): Observable<T>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T>(v1: ObservableInput<T>, concurrent: number, scheduler: SchedulerLike): Observable<T>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2>(v1: ObservableInput<T>, v2: ObservableInput<T2>, scheduler: SchedulerLike): Observable<T | T2>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2>(v1: ObservableInput<T>, v2: ObservableInput<T2>, concurrent: number, scheduler: SchedulerLike): Observable<T | T2>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, scheduler: SchedulerLike): Observable<T | T2 | T3>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, concurrent: number, scheduler: SchedulerLike): Observable<T | T2 | T3>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, concurrent: number, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4, T5>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, v5: ObservableInput<T5>, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4 | T5>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4, T5>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, v5: ObservableInput<T5>, concurrent: number, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4 | T5>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4, T5, T6>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, v5: ObservableInput<T5>, v6: ObservableInput<T6>, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4 | T5 | T6>;
-/** @deprecated The scheduler argument is deprecated, use {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
+/** @deprecated The scheduler argument is deprecated, use scheduled and mergeAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function merge<T, T2, T3, T4, T5, T6>(v1: ObservableInput<T>, v2: ObservableInput<T2>, v3: ObservableInput<T3>, v4: ObservableInput<T4>, v5: ObservableInput<T5>, v6: ObservableInput<T6>, concurrent: number, scheduler: SchedulerLike): Observable<T | T2 | T3 | T4 | T5 | T6>;
 
 export function merge<T>(v1: ObservableInput<T>): Observable<T>;