docs(deprecations): add scheduler deprecation page and adjust depreca…

…tion messages

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 barely 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)
+- [combineLates](/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(of([1,2,3]), asyncScheduler).subscribe(x => console.log(x));
+```
+
+### Refactoring of `merge`, `concat`, `startWith` and `endWith`
+
+In case you used to pass a scheduler argument to one of these operators you propably 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 want to use [mergeAll](/api/operators/mergeAll) to refactor the deprecated usage of `merge`.
+
+### Refactoring `combineLatest`
+
+Unfortunately, there's no point in using `scheduled` with `combineLatest`. You rather want to leverage [`subscribeOn`](/api/operators/subscribeOn) or [`observeOn`](/api/operators/observeOn) depending on your goals. 
+
+E.g. code that used to look like this:
+
+```ts
+import { combineLatest, timer, asyncScheduler } from 'rxjs'; 
+
+combineLatest(
+  [timer(0, 1000), timer(500, 500)],
+  asyncScheduler
+).subscribe(console.log)
+```
+
+would become:
+
+```ts
+import { combineLatest, timer, asyncScheduler } from 'rxjs'; 
+import { subscribeOn } from 'rxjs/operators'
+
+combineLatest(
+  [timer(0, 1000), timer(500, 500)],
+).pipe(
+  subscribeOn(asyncScheduler)
+).subscribe(console.log)
+```

docs_app/content/navigation.json

@@ -91,8 +91,8 @@
 			"title": "Deprecations & Breaking Changes",
 			"children": [
 				{
-					"url": "deprecations/tuple-argument",
-					"title": "Operator Array Argument"
+					"url": "deprecations/scheduler-argument",
+					"title": "Scheduler Argument"
 				}
 
 			]

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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link subscribeOn} and/or {@link observeOn}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled} and {@link concatAll}. Details: {@link 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 {@link scheduled}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link 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 {@link scheduled} and {@link mergeAll}. Details: {@link https://rxjs.dev/deprecations/scheduler-argument} */
 export function merge<T, T2, T3, T4, T5, T6>(
   v1: ObservableInput<T>,
   v2: ObservableInput<T2>,