[docs]: Create Deprecation page per deprecation group (#5426)

* docs(deprecation): init deprecation section

* docs(deprecations): add scheduler deprecation page and adjust deprecation messages

* docs(deprecations): remove jsdoc style from deprecation message

* chore: fix typos

* chore: make changes to address my comments

Co-authored-by: Jan-Niklas Wortmann <[email protected]>
Co-authored-by: Nicholas Jamieson <[email protected]>

docs_app/content/deprecations/scheduler-argument.md

@@ -0,0 +1,101 @@
+# Scheduler Argument
+
+To limit the API surface of some operators, but also prepare for a [major refactoring in V8](https://github.com/ReactiveX/rxjs/pull/4583), we
+agreed on deprecating the `scheduler` argument from many operators. It solely deprecates those methods where this argument is rarely used. So `time` related
+operators, like [`interval`](https://rxjs.dev/api/index/function/interval) are not affected by this deprecation.
+
+To support this transition the [scheduled creation function](/api/index/function/scheduled) was added.
+
+<div class="alert is-important">
+    <span>
+        This deprecation was introduced in **RxJS 6.5** and will become breaking with **RxJS 8**.
+    </span>
+</div>
+
+## Operators affected by this Change
+
+- [from](/api/index/function/from)
+- [of](/api/index/function/of)
+- [merge](/api/index/function/merge)
+- [concat](/api/index/function/concat)
+- [startWith](/api/operators/startWith)
+- [endWith](/api/operators/endWith)
+- [combineLatest](/api/index/function/combineLatest)
+
+## How to Refactor
+
+If you use any other operator from the list above and using the `scheduler` argument, you have to three potential refactoring options.
+
+### Refactoring of `of` and `from`
+
+`scheduled` is kinda copying the behavior of `from`. Therefore if you used `from`  with a `scheduler` argument, you can just replace them.
+
+For the `of` creation function you need to this Observable with `scheduled` and instead of passing the `scheduler` argument to `of` pass it to `scheduled`.
+Following code example demonstrate this process.
+
+```ts
+import { of, asyncScheduler, scheduled } from 'rxjs'; 
+
+// Deprecated approach
+of([1,2,3], asyncScheduler).subscribe(x => console.log(x));
+// suggested approach
+scheduled([1,2,3], asyncScheduler).subscribe(x => console.log(x));
+```
+
+### Refactoring of `merge`, `concat`, `combineLatest`, `startWith` and `endWith`
+
+In case you used to pass a scheduler argument to one of these operators you probably had code like this:
+
+```ts
+import { concat, of, asyncScheduler } from 'rxjs'; 
+
+concat(
+  of('hello '),
+  of('World'),
+  asyncScheduler
+).subscribe(x => console.log(x));
+```
+
+To work around this deprecation you can leverage the [`scheduled`](/api/index/function/scheduled) function.
+
+```ts
+import { scheduled, of, asyncScheduler } from 'rxjs'; 
+import { concatAll } from 'rxjs/operators'
+
+scheduled(
+  [of('hello '), of('World')],
+  asyncScheduler
+).pipe(
+  concatAll()
+).subscribe(x => console.log(x));
+```
+
+You can apply this pattern to refactor deprecated usage of `concat`, `startWith` and `endWith` but do notice that you will want to use [mergeAll](/api/operators/mergeAll) to refactor the deprecated usage of `merge`.
+
+With `combineLatest`, you will want to use [combineAll](/api/operators/combineAll)
+
+E.g. code that used to look like this:
+
+```ts
+import { combineLatest, of, asyncScheduler } from 'rxjs';
+
+combineLatest(
+  of('hello '),
+  of('World'),
+  asyncScheduler
+).subscribe(console.log)
+```
+
+would become:
+
+```ts
+import { scheduled, of, asyncScheduler } from 'rxjs';
+import { combineAll } from 'rxjs/operators'
+
+scheduled(
+  [of('hello '), of('World')],
+  asyncScheduler
+).pipe(
+  combineAll()
+).subscribe(x => console.log(x));
+```

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 Observable 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.
+

docs_app/content/navigation.json

@@ -84,12 +84,17 @@
 				{
 					"url": "guide/v6/pipeable-operators",
 					"title": "Pipeable Operators"
-				},
+				}
+			]
+		},
+		{
+			"title": "Deprecations & Breaking Changes",
+			"children": [
 				{
-					"url": "api/deprecations",
-					"title": "Deprecations",
-					"tooltip": "List of Deprecations"
+					"url": "deprecations/scheduler-argument",
+					"title": "Scheduler Argument"
 				}
+
 			]
 		},
 		{

docs_app/tools/transforms/angular-content-package/index.js

@@ -19,7 +19,7 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
     readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([
       {
         basePath: CONTENTS_PATH,
-        include: CONTENTS_PATH + '/{cookbook,guide,tutorial}/**/*.md',
+        include: CONTENTS_PATH + '/{deprecations,guide,tutorial}/**/*.md',
         fileReader: 'contentFileReader'
       },
       {

src/internal/observable/combineLatest.ts

@@ -177,19 +177,19 @@ export function combineLatest<
 ): Observable<R>;
 
 // With a scheduler (deprecated)
-/** @deprecated Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<O1 extends ObservableInput<any>>(sources: [O1], scheduler: SchedulerLike): Observable<[ObservedValueOf<O1>]>;
-/** @deprecated Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. 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 Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. 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 Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<
   O1 extends ObservableInput<any>,
   O2 extends ObservableInput<any>,
@@ -199,7 +199,7 @@ export function combineLatest<
   sources: [O1, O2, O3, O4],
   scheduler: SchedulerLike
 ): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>]>;
-/** @deprecated Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<
   O1 extends ObservableInput<any>,
   O2 extends ObservableInput<any>,
@@ -210,7 +210,7 @@ export function combineLatest<
   sources: [O1, O2, O3, O4, O5],
   scheduler: SchedulerLike
 ): Observable<[ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>, ObservedValueOf<O5>]>;
-/** @deprecated Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. Details: https://rxjs.dev/deprecations/scheduler-argument */
 export function combineLatest<
   O1 extends ObservableInput<any>,
   O2 extends ObservableInput<any>,
@@ -224,7 +224,7 @@ export function combineLatest<
 ): Observable<
   [ObservedValueOf<O1>, ObservedValueOf<O2>, ObservedValueOf<O3>, ObservedValueOf<O4>, ObservedValueOf<O5>, ObservedValueOf<O6>]
 >;
-/** @deprecated Passing a scheduler here is deprecated, use {@link subscribeOn} and/or {@link observeOn} instead */
+/** @deprecated The scheduler argument is deprecated, use scheduled and combineAll. 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

@@ -5,17 +5,17 @@ import { isScheduler } from '../util/isScheduler';
 import { fromArray } from './fromArray';
 
 /* tslint:disable:max-line-length */
-/** @deprecated remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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 remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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 remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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 remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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 remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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 remove in v8. Passing a scheduler to concat is deprecated, please use {@link scheduled} and {@link concatAll} `scheduled([o1, o2], scheduler).pipe(concatAll())` */
+/** @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

@@ -16,7 +16,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 use {@link scheduled} instead. */
+/** @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>>;
 
 /**
@@ -149,4 +149,4 @@ function subscribeTo<T>(result: ObservableInput<T>): (subscriber: Subscriber<T>)
       + ' You can provide an Observable, Promise, Array, AsyncIterable, or Iterable.';
     throw new TypeError(msg);
   }
-};
+}

src/internal/observable/merge.ts

@@ -9,43 +9,43 @@ import { from } from './from';
 import { EMPTY } from './empty';
 
 /* tslint:disable:max-line-length */
-/** @deprecated use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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 use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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>,
@@ -54,7 +54,7 @@ export function merge<T, T2, T3, T4>(
   concurrent: number,
   scheduler: SchedulerLike
 ): Observable<T | T2 | T3 | T4>;
-/** @deprecated use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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>,
@@ -63,7 +63,7 @@ export function merge<T, T2, T3, T4, T5>(
   v5: ObservableInput<T5>,
   scheduler: SchedulerLike
 ): Observable<T | T2 | T3 | T4 | T5>;
-/** @deprecated use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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>,
@@ -73,7 +73,7 @@ export function merge<T, T2, T3, T4, T5>(
   concurrent: number,
   scheduler: SchedulerLike
 ): Observable<T | T2 | T3 | T4 | T5>;
-/** @deprecated use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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>,
@@ -83,7 +83,7 @@ export function merge<T, T2, T3, T4, T5, T6>(
   v6: ObservableInput<T6>,
   scheduler: SchedulerLike
 ): Observable<T | T2 | T3 | T4 | T5 | T6>;
-/** @deprecated use {@link scheduled} and {@link mergeAll} (e.g. `scheduled([ob1, ob2, ob3], scheduler).pipe(mergeAll())*/
+/** @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>,