From 14b48904d6fe29ce9a4a78d8c29a1cf834741176 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mladen=20Jakovljevi=C4=87?= Date: Tue, 19 May 2020 23:35:34 +0200 Subject: [PATCH 1/3] docs(operators): fix @return docs --- src/internal/operators/audit.ts | 2 +- src/internal/operators/auditTime.ts | 2 +- src/internal/operators/buffer.ts | 4 ++-- src/internal/operators/bufferCount.ts | 2 +- src/internal/operators/bufferTime.ts | 2 +- src/internal/operators/bufferToggle.ts | 2 +- src/internal/operators/bufferWhen.ts | 2 +- src/internal/operators/catchError.ts | 10 +++++----- src/internal/operators/combineLatestAll.ts | 3 +++ src/internal/operators/combineLatestWith.ts | 2 ++ src/internal/operators/concatAll.ts | 4 ++-- src/internal/operators/concatMap.ts | 8 ++++---- src/internal/operators/concatMapTo.ts | 6 +++--- src/internal/operators/concatWith.ts | 3 +++ src/internal/operators/count.ts | 2 ++ src/internal/operators/debounce.ts | 4 ++-- src/internal/operators/debounceTime.ts | 6 +++--- src/internal/operators/defaultIfEmpty.ts | 6 +++--- src/internal/operators/delay.ts | 4 ++-- src/internal/operators/delayWhen.ts | 6 +++--- src/internal/operators/dematerialize.ts | 5 +++-- src/internal/operators/distinct.ts | 3 ++- src/internal/operators/distinctUntilChanged.ts | 4 ++++ src/internal/operators/distinctUntilKeyChanged.ts | 3 ++- src/internal/operators/elementAt.ts | 5 +++-- src/internal/operators/endWith.ts | 5 ++++- src/internal/operators/every.ts | 3 ++- src/internal/operators/exhaustAll.ts | 5 +++-- src/internal/operators/exhaustMap.ts | 6 +++--- src/internal/operators/expand.ts | 6 +++--- src/internal/operators/filter.ts | 2 ++ src/internal/operators/finalize.ts | 3 ++- src/internal/operators/find.ts | 4 ++-- src/internal/operators/findIndex.ts | 4 ++-- src/internal/operators/first.ts | 4 ++-- src/internal/operators/groupBy.ts | 7 +++---- src/internal/operators/ignoreElements.ts | 5 +++-- src/internal/operators/isEmpty.ts | 3 ++- src/internal/operators/last.ts | 5 +++-- src/internal/operators/map.ts | 4 ++-- src/internal/operators/mapTo.ts | 4 ++-- src/internal/operators/materialize.ts | 6 +++--- src/internal/operators/max.ts | 3 ++- src/internal/operators/mergeAll.ts | 4 ++-- src/internal/operators/mergeMap.ts | 8 ++++---- src/internal/operators/mergeMapTo.ts | 6 +++--- src/internal/operators/mergeScan.ts | 2 +- src/internal/operators/mergeWith.ts | 2 ++ src/internal/operators/min.ts | 3 ++- src/internal/operators/multicast.ts | 4 ++++ src/internal/operators/observeOn.ts | 4 ++-- src/internal/operators/onErrorResumeNext.ts | 7 ++++--- src/internal/operators/pairwise.ts | 2 +- src/internal/operators/partition.ts | 6 +++--- src/internal/operators/pluck.ts | 5 +++-- src/internal/operators/publish.ts | 3 ++- src/internal/operators/publishBehavior.ts | 2 +- src/internal/operators/publishLast.ts | 7 ++++++- src/internal/operators/race.ts | 5 +++-- src/internal/operators/raceWith.ts | 2 ++ src/internal/operators/reduce.ts | 4 ++-- src/internal/operators/refCount.ts | 5 +++++ src/internal/operators/repeat.ts | 4 ++-- src/internal/operators/repeatWhen.ts | 3 ++- src/internal/operators/retry.ts | 3 ++- src/internal/operators/retryWhen.ts | 3 ++- src/internal/operators/sample.ts | 8 ++++---- src/internal/operators/sampleTime.ts | 5 +++-- src/internal/operators/scan.ts | 1 + src/internal/operators/sequenceEqual.ts | 5 +++-- src/internal/operators/share.ts | 6 ++++++ src/internal/operators/shareReplay.ts | 5 +++-- src/internal/operators/single.ts | 5 +++-- src/internal/operators/skip.ts | 3 ++- src/internal/operators/skipLast.ts | 3 ++- src/internal/operators/skipUntil.ts | 5 +++-- src/internal/operators/skipWhile.ts | 4 ++-- src/internal/operators/startWith.ts | 2 ++ src/internal/operators/subscribeOn.ts | 3 ++- src/internal/operators/switchAll.ts | 4 ++++ src/internal/operators/switchMap.ts | 8 ++++---- src/internal/operators/switchMapTo.ts | 9 +++++---- src/internal/operators/switchScan.ts | 2 +- src/internal/operators/take.ts | 6 +++--- src/internal/operators/takeLast.ts | 4 ++-- src/internal/operators/takeUntil.ts | 4 ++-- src/internal/operators/takeWhile.ts | 6 +++--- src/internal/operators/tap.ts | 2 ++ src/internal/operators/throttle.ts | 4 ++-- src/internal/operators/throttleTime.ts | 4 ++-- src/internal/operators/throwIfEmpty.ts | 2 ++ src/internal/operators/timeInterval.ts | 3 ++- src/internal/operators/timeout.ts | 3 +++ src/internal/operators/timeoutWith.ts | 3 +++ src/internal/operators/timestamp.ts | 4 +++- src/internal/operators/toArray.ts | 7 ++++--- src/internal/operators/window.ts | 2 +- src/internal/operators/windowCount.ts | 4 ++-- src/internal/operators/windowTime.ts | 3 ++- src/internal/operators/windowToggle.ts | 4 ++-- src/internal/operators/windowWhen.ts | 4 ++-- src/internal/operators/withLatestFrom.ts | 6 +++--- src/internal/operators/zipWith.ts | 3 +++ 103 files changed, 262 insertions(+), 167 deletions(-) diff --git a/src/internal/operators/audit.ts b/src/internal/operators/audit.ts index 056d7e50dd..eaa7da4e61 100644 --- a/src/internal/operators/audit.ts +++ b/src/internal/operators/audit.ts @@ -46,7 +46,7 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @param durationSelector A function * that receives a value from the source Observable, for computing the silencing * duration, returned as an Observable or a Promise. - * @return An Observable that performs rate-limiting of + * @return A function that returns an Observable that performs rate-limiting of * emissions from the source Observable. */ export function audit(durationSelector: (value: T) => ObservableInput): MonoTypeOperatorFunction { diff --git a/src/internal/operators/auditTime.ts b/src/internal/operators/auditTime.ts index d5cb94af1f..7777ddce18 100644 --- a/src/internal/operators/auditTime.ts +++ b/src/internal/operators/auditTime.ts @@ -47,7 +47,7 @@ import { MonoTypeOperatorFunction, SchedulerLike } from '../types'; * by the optional `scheduler`. * @param {SchedulerLike} [scheduler=async] The {@link SchedulerLike} to use for * managing the timers that handle the rate-limiting behavior. - * @return {Observable} An Observable that performs rate-limiting of + * @return A function that returns an Observable that performs rate-limiting of * emissions from the source Observable. */ export function auditTime(duration: number, scheduler: SchedulerLike = async): MonoTypeOperatorFunction { diff --git a/src/internal/operators/buffer.ts b/src/internal/operators/buffer.ts index 6f34c6f0d4..47c75b5f45 100644 --- a/src/internal/operators/buffer.ts +++ b/src/internal/operators/buffer.ts @@ -39,8 +39,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param {Observable} closingNotifier An Observable that signals the * buffer to be emitted on the output Observable. - * @return {Observable} An Observable of buffers, which are arrays of - * values. + * @return A function that returns an Observable of buffers, which are arrays + * of values. */ export function buffer(closingNotifier: Observable): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/bufferCount.ts b/src/internal/operators/bufferCount.ts index 3f82944e34..854a85f5be 100644 --- a/src/internal/operators/bufferCount.ts +++ b/src/internal/operators/bufferCount.ts @@ -54,7 +54,7 @@ import { arrRemove } from '../util/arrRemove'; * For example if `startBufferEvery` is `2`, then a new buffer will be started * on every other value from the source. A new buffer is started at the * beginning of the source by default. - * @return {Observable} An Observable of arrays of buffered values. + * @return A function that returns an Observable of arrays of buffered values. */ export function bufferCount(bufferSize: number, startBufferEvery: number | null = null): OperatorFunction { // If no `startBufferEvery` value was supplied, then we're diff --git a/src/internal/operators/bufferTime.ts b/src/internal/operators/bufferTime.ts index 35e08945d6..042f701bf9 100644 --- a/src/internal/operators/bufferTime.ts +++ b/src/internal/operators/bufferTime.ts @@ -74,7 +74,7 @@ export function bufferTime( * @param {number} [maxBufferSize] The maximum buffer size. * @param {SchedulerLike} [scheduler=async] The scheduler on which to schedule the * intervals that determine buffer boundaries. - * @return {Observable} An observable of arrays of buffered values. + * @return A function that returns an Observable of arrays of buffered values. */ export function bufferTime(bufferTimeSpan: number, ...otherArgs: any[]): OperatorFunction { const scheduler = popScheduler(otherArgs) ?? asyncScheduler; diff --git a/src/internal/operators/bufferToggle.ts b/src/internal/operators/bufferToggle.ts index b72cdb7ecd..8ea0fd6409 100644 --- a/src/internal/operators/bufferToggle.ts +++ b/src/internal/operators/bufferToggle.ts @@ -48,7 +48,7 @@ import { arrRemove } from '../util/arrRemove'; * the value emitted by the `openings` observable and returns a Subscribable or Promise, * which, when it emits, signals that the associated buffer should be emitted * and cleared. - * @return An observable of arrays of buffered values. + * @return A function that returns an Observable of arrays of buffered values. */ export function bufferToggle( openings: ObservableInput, diff --git a/src/internal/operators/bufferWhen.ts b/src/internal/operators/bufferWhen.ts index fb1a68eb37..17e707efb0 100644 --- a/src/internal/operators/bufferWhen.ts +++ b/src/internal/operators/bufferWhen.ts @@ -43,7 +43,7 @@ import { innerFrom } from '../observable/from'; * * @param {function(): Observable} closingSelector A function that takes no * arguments and returns an Observable that signals buffer closure. - * @return {Observable} An observable of arrays of buffered values. + * @return A function that returns an Observable of arrays of buffered values. */ export function bufferWhen(closingSelector: () => ObservableInput): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/catchError.ts b/src/internal/operators/catchError.ts index fb06adda27..fe120d31fd 100644 --- a/src/internal/operators/catchError.ts +++ b/src/internal/operators/catchError.ts @@ -97,11 +97,11 @@ export function catchError>( * @see {@link retry } * @see {@link retryWhen} * - * @param {function} selector a function that takes as arguments `err`, which is the error, and `caught`, which - * is the source observable, in case you'd like to "retry" that observable by returning it again. Whatever observable - * is returned by the `selector` will be used to continue the observable chain. - * @return {Observable} An observable that originates from either the source or the observable returned by the - * catch `selector` function. + * @param {function} selector a function that takes as arguments `err`, which is the error, and `caught`, which + * is the source observable, in case you'd like to "retry" that observable by returning it again. Whatever observable + * is returned by the `selector` will be used to continue the observable chain. + * @return A function that returns an Observable that originates from either + * the source or the Observable returned by the `selector` function. */ export function catchError>( selector: (err: any, caught: Observable) => O diff --git a/src/internal/operators/combineLatestAll.ts b/src/internal/operators/combineLatestAll.ts index d9e4bf1074..7d06b87bcc 100644 --- a/src/internal/operators/combineLatestAll.ts +++ b/src/internal/operators/combineLatestAll.ts @@ -6,6 +6,7 @@ export function combineLatestAll(): OperatorFunction, T[]> export function combineLatestAll(): OperatorFunction; export function combineLatestAll(project: (...values: T[]) => R): OperatorFunction, R>; export function combineLatestAll(project: (...values: Array) => R): OperatorFunction; + /** * Flattens an Observable-of-Observables by applying {@link combineLatest} when the Observable-of-Observables completes. * @@ -50,6 +51,8 @@ export function combineLatestAll(project: (...values: Array) => R): Oper * * @param project optional function to map the most recent values from each inner Observable into a new result. * Takes each of the most recent values from each collected inner Observable as arguments, in order. + * @return A function that returns an Observable that flattens Observables + * emitted by the source Observable. */ export function combineLatestAll(project?: (...values: Array) => R) { return joinAllInternals(combineLatest, project); diff --git a/src/internal/operators/combineLatestWith.ts b/src/internal/operators/combineLatestWith.ts index 9d15cb3535..3d96e5d43d 100644 --- a/src/internal/operators/combineLatestWith.ts +++ b/src/internal/operators/combineLatestWith.ts @@ -36,6 +36,8 @@ import { combineLatest } from './combineLatest'; * * ``` * @param otherSources the other sources to subscribe to. + * @return A function that returns an Observable that emits the latest + * emissions from both source and provided Observables. */ export function combineLatestWith( ...otherSources: [...ObservableInputTuple] diff --git a/src/internal/operators/concatAll.ts b/src/internal/operators/concatAll.ts index 446337e105..727b7f1bd3 100644 --- a/src/internal/operators/concatAll.ts +++ b/src/internal/operators/concatAll.ts @@ -54,8 +54,8 @@ import { OperatorFunction, ObservableInput, ObservedValueOf } from '../types'; * @see {@link switchMap} * @see {@link zipAll} * - * @return {Observable} An Observable emitting values from all the inner - * Observables concatenated. + * @return A function that returns an Observable emitting values from all the + * inner Observables concatenated. */ export function concatAll>(): OperatorFunction> { return mergeAll(1); diff --git a/src/internal/operators/concatMap.ts b/src/internal/operators/concatMap.ts index b78cd92b40..0c4c5702bf 100644 --- a/src/internal/operators/concatMap.ts +++ b/src/internal/operators/concatMap.ts @@ -71,10 +71,10 @@ export function concatMap>( * @param {function(value: T, ?index: number): ObservableInput} project A function * that, when applied to an item emitted by the source Observable, returns an * Observable. - * @return {Observable} An Observable that emits the result of applying the - * projection function (and the optional deprecated `resultSelector`) to each item emitted - * by the source Observable and taking values from each projected inner - * Observable sequentially. + * @return A function that returns an Observable that emits the result of + * applying the projection function (and the optional deprecated + * `resultSelector`) to each item emitted by the source Observable and taking + * values from each projected inner Observable sequentially. */ export function concatMap>( project: (value: T, index: number) => O, diff --git a/src/internal/operators/concatMapTo.ts b/src/internal/operators/concatMapTo.ts index a94a01b49f..e23b2cc36b 100644 --- a/src/internal/operators/concatMapTo.ts +++ b/src/internal/operators/concatMapTo.ts @@ -66,9 +66,9 @@ export function concatMapTo>( * * @param {ObservableInput} innerObservable An Observable to replace each value from * the source Observable. - * @return {Observable} An observable of values merged together by joining the - * passed observable with itself, one after the other, for each value emitted - * from the source. + * @return A function that returns an Observable of values merged together by + * joining the passed Observable with itself, one after the other, for each + * value emitted from the source. */ export function concatMapTo>( innerObservable: O, diff --git a/src/internal/operators/concatWith.ts b/src/internal/operators/concatWith.ts index edec7d99be..71bde331c7 100644 --- a/src/internal/operators/concatWith.ts +++ b/src/internal/operators/concatWith.ts @@ -38,6 +38,9 @@ import { concat } from './concat'; * ``` * * @param otherSources Other observable sources to subscribe to, in sequence, after the original source is complete. + * @return A function that returns an Observable that concatenates + * subscriptions to the source and provided Observables subscribing to the next + * only once the current subscription completes. */ export function concatWith( ...otherSources: [...ObservableInputTuple] diff --git a/src/internal/operators/count.ts b/src/internal/operators/count.ts index 21fcff92db..81d037be3f 100644 --- a/src/internal/operators/count.ts +++ b/src/internal/operators/count.ts @@ -52,6 +52,8 @@ import { reduce } from './reduce'; * determine whether or not to increment the count. Return `true` to increment the count, * and return `false` to keep the count the same. * If the predicate is not provided, every value will be counted. + * @return A function that returns an Observable that emits one number that + * represents the count of emissions. */ export function count(predicate?: (value: T, index: number) => boolean): OperatorFunction { diff --git a/src/internal/operators/debounce.ts b/src/internal/operators/debounce.ts index d64d2533a4..87b4f15e6b 100644 --- a/src/internal/operators/debounce.ts +++ b/src/internal/operators/debounce.ts @@ -58,8 +58,8 @@ import { innerFrom } from '../observable/from'; * @param durationSelector A function * that receives a value from the source Observable, for computing the timeout * duration for each source value, returned as an Observable or a Promise. - * @return An Observable that delays the emissions of the source - * Observable by the specified duration Observable returned by + * @return A function that returns an Observable that delays the emissions of + * the source Observable by the specified duration Observable returned by * `durationSelector`, and may drop some values if they occur too frequently. */ export function debounce(durationSelector: (value: T) => ObservableInput): MonoTypeOperatorFunction { diff --git a/src/internal/operators/debounceTime.ts b/src/internal/operators/debounceTime.ts index 177fcbaf64..e72af673e7 100644 --- a/src/internal/operators/debounceTime.ts +++ b/src/internal/operators/debounceTime.ts @@ -57,9 +57,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * source value. * @param {SchedulerLike} [scheduler=async] The {@link SchedulerLike} to use for * managing the timers that handle the timeout for each value. - * @return {Observable} An Observable that delays the emissions of the source - * Observable by the specified `dueTime`, and may drop some values if they occur - * too frequently. + * @return A function that returns an Observable that delays the emissions of + * the source Observable by the specified `dueTime`, and may drop some values + * if they occur too frequently. */ export function debounceTime(dueTime: number, scheduler: SchedulerLike = asyncScheduler): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/defaultIfEmpty.ts b/src/internal/operators/defaultIfEmpty.ts index ceba8d4962..24ba90c23f 100644 --- a/src/internal/operators/defaultIfEmpty.ts +++ b/src/internal/operators/defaultIfEmpty.ts @@ -32,9 +32,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param defaultValue The default value used if the source * Observable is empty. - * @return An Observable that emits either the specified - * `defaultValue` if the source Observable emits no items, or the values emitted - * by the source Observable. + * @return A function that returns an Observable that emits either the + * specified `defaultValue` if the source Observable emits no items, or the + * values emitted by the source Observable. */ export function defaultIfEmpty(defaultValue: R): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/delay.ts b/src/internal/operators/delay.ts index 7d9442969a..22ef2e33db 100644 --- a/src/internal/operators/delay.ts +++ b/src/internal/operators/delay.ts @@ -48,8 +48,8 @@ import { timer } from '../observable/timer'; * a `Date` until which the emission of the source items is delayed. * @param {SchedulerLike} [scheduler=async] The {@link SchedulerLike} to use for * managing the timers that handle the time-shift for each item. - * @return {Observable} An Observable that delays the emissions of the source - * Observable by the specified timeout or Date. + * @return A function that returns an Observable that delays the emissions of + * the source Observable by the specified timeout or Date. */ export function delay(due: number | Date, scheduler: SchedulerLike = asyncScheduler): MonoTypeOperatorFunction { const duration = timer(due, scheduler); diff --git a/src/internal/operators/delayWhen.ts b/src/internal/operators/delayWhen.ts index b0297afd5b..3872169293 100644 --- a/src/internal/operators/delayWhen.ts +++ b/src/internal/operators/delayWhen.ts @@ -72,9 +72,9 @@ export function delayWhen(delayDurationSelector: (value: T, index: number) => * until the Observable returned from this function emits a value. * @param {Observable} subscriptionDelay An Observable that triggers the * subscription to the source Observable once it emits any value. - * @return {Observable} An Observable that delays the emissions of the source - * Observable by an amount of time specified by the Observable returned by - * `delayDurationSelector`. + * @return A function that returns an Observable that delays the emissions of + * the source Observable by an amount of time specified by the Observable + * returned by `delayDurationSelector`. */ export function delayWhen( delayDurationSelector: (value: T, index: number) => Observable, diff --git a/src/internal/operators/dematerialize.ts b/src/internal/operators/dematerialize.ts index 3384141665..2c6e8e3d8b 100644 --- a/src/internal/operators/dematerialize.ts +++ b/src/internal/operators/dematerialize.ts @@ -47,8 +47,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * ``` * @see {@link materialize} * - * @return {Observable} An Observable that emits items and notifications - * embedded in Notification objects emitted by the source Observable. + * @return A function that returns an Observable that emits items and + * notifications embedded in Notification objects emitted by the source + * Observable. */ export function dematerialize>(): OperatorFunction> { return operate((source, subscriber) => { diff --git a/src/internal/operators/distinct.ts b/src/internal/operators/distinct.ts index 9723360615..8faa00701a 100644 --- a/src/internal/operators/distinct.ts +++ b/src/internal/operators/distinct.ts @@ -68,7 +68,8 @@ import { noop } from '../util/noop'; * * @param {function} [keySelector] Optional function to select which value you want to check as distinct. * @param {Observable} [flushes] Optional Observable for flushing the internal HashSet of the operator. - * @return {Observable} An Observable that emits items from the source Observable with distinct values. + * @return A function that returns an Observable that emits items from the + * source Observable with distinct values. */ export function distinct(keySelector?: (value: T) => K, flushes?: Observable): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/distinctUntilChanged.ts b/src/internal/operators/distinctUntilChanged.ts index f7fd07b531..30f87bcc96 100644 --- a/src/internal/operators/distinctUntilChanged.ts +++ b/src/internal/operators/distinctUntilChanged.ts @@ -90,6 +90,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param comparator A function used to compare the previous and current values for * equality. Defaults to a `===` check. + * @return A function that returns an Observable that emits items from the + * source Observable with distinct values. */ export function distinctUntilChanged(comparator?: (previous: T, current: T) => boolean): MonoTypeOperatorFunction; @@ -134,6 +136,8 @@ export function distinctUntilChanged(comparator?: (previous: T, current: T) = * @param comparator A function used to compare the previous and current keys for * equality. Defaults to a `===` check. * @param keySelector Used to select a key value to be passed to the `comparator`. + * @return A function that returns an Observable that emits items from the + * source Observable with distinct values. */ export function distinctUntilChanged( comparator: (previous: K, current: K) => boolean, diff --git a/src/internal/operators/distinctUntilKeyChanged.ts b/src/internal/operators/distinctUntilKeyChanged.ts index af16f8770d..45112b9219 100644 --- a/src/internal/operators/distinctUntilKeyChanged.ts +++ b/src/internal/operators/distinctUntilKeyChanged.ts @@ -72,7 +72,8 @@ export function distinctUntilKeyChanged(key: K, compare: ( * * @param {string} key String key for object property lookup on each item. * @param {function} [compare] Optional comparison function called to test if an item is distinct from the previous item in the source. - * @return {Observable} An Observable that emits items from the source Observable with distinct values based on the key specified. + * @return A function that returns an Observable that emits items from the + * source Observable with distinct values based on the key specified. */ export function distinctUntilKeyChanged(key: K, compare?: (x: T[K], y: T[K]) => boolean): MonoTypeOperatorFunction { return distinctUntilChanged((x: T, y: T) => compare ? compare(x[key], y[key]) : x[key] === y[key]); diff --git a/src/internal/operators/elementAt.ts b/src/internal/operators/elementAt.ts index 464149ad6a..21454089e0 100644 --- a/src/internal/operators/elementAt.ts +++ b/src/internal/operators/elementAt.ts @@ -49,8 +49,9 @@ import { take } from './take'; * @param {number} index Is the number `i` for the i-th source emission that has * happened since the subscription, starting from the number `0`. * @param {T} [defaultValue] The default value returned for missing indices. - * @return {Observable} An Observable that emits a single item, if it is found. - * Otherwise, will emit the default value if given. If not, then emits an error. + * @return A function that returns an Observable that emits a single item, if + * it is found. Otherwise, it will emit the default value if given. If not, it + * emits an error. */ export function elementAt(index: number, defaultValue?: D): OperatorFunction { if (index < 0) { diff --git a/src/internal/operators/endWith.ts b/src/internal/operators/endWith.ts index d5fc7f2fe8..b2978c11f0 100644 --- a/src/internal/operators/endWith.ts +++ b/src/internal/operators/endWith.ts @@ -55,7 +55,10 @@ export function endWith(...args: A): OperatorFunct * // "interval ended by click" * ``` * - * @param values - Items you want the modified Observable to emit last. + * @param values Items you want the modified Observable to emit last. + * @return A function that returns an Observable that emits all values from the + * source, then synchronously emits the provided value(s) immediately after the + * source completes. * * @see {@link startWith} * @see {@link concat} diff --git a/src/internal/operators/every.ts b/src/internal/operators/every.ts index 458ff5d0f4..09e8568f1c 100644 --- a/src/internal/operators/every.ts +++ b/src/internal/operators/every.ts @@ -35,7 +35,8 @@ export function every(predicate: (value: T, index: number, source: Observable * * @param {function} predicate A function for determining if an item meets a specified condition. * @param {any} [thisArg] Optional object to use for `this` in the callback. - * @return {Observable} An Observable of booleans that determines if all items of the source Observable meet the condition specified. + * @return A function that returns an Observable of booleans that determines if + * all items of the source Observable meet the condition specified. */ export function every( predicate: (value: T, index: number, source: Observable) => boolean, diff --git a/src/internal/operators/exhaustAll.ts b/src/internal/operators/exhaustAll.ts index 200431c2e2..54d9927a37 100644 --- a/src/internal/operators/exhaustAll.ts +++ b/src/internal/operators/exhaustAll.ts @@ -43,8 +43,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link exhaustMap} * @see {@link zipAll} * - * @return {Observable} An Observable that takes a source of Observables and propagates the first observable - * exclusively until it completes before subscribing to the next. + * @return A function that returns an Observable that takes a source of + * Observables and propagates the first Observable exclusively until it + * completes before subscribing to the next. */ export function exhaustAll>(): OperatorFunction> { return operate((source, subscriber) => { diff --git a/src/internal/operators/exhaustMap.ts b/src/internal/operators/exhaustMap.ts index a9e46ab29d..08efd367de 100644 --- a/src/internal/operators/exhaustMap.ts +++ b/src/internal/operators/exhaustMap.ts @@ -61,9 +61,9 @@ export function exhaustMap( * @param {function(value: T, ?index: number): ObservableInput} project A function * that, when applied to an item emitted by the source Observable, returns an * Observable. - * @return {Observable} An Observable containing projected Observables - * of each item of the source, ignoring projected Observables that start before - * their preceding Observable has completed. + * @return A function that returns an Observable containing projected + * Observables of each item of the source, ignoring projected Observables that + * start before their preceding Observable has completed. */ export function exhaustMap>( project: (value: T, index: number) => O, diff --git a/src/internal/operators/expand.ts b/src/internal/operators/expand.ts index b8523cbeab..907164adbe 100644 --- a/src/internal/operators/expand.ts +++ b/src/internal/operators/expand.ts @@ -64,9 +64,9 @@ export function expand>( * Observables being subscribed to concurrently. * @param {SchedulerLike} [scheduler=null] The {@link SchedulerLike} to use for subscribing to * each projected inner Observable. - * @return {Observable} An Observable that emits the source values and also - * result of applying the projection function to each value emitted on the - * output Observable and merging the results of the Observables obtained + * @return A function that returns an Observable that emits the source values + * and also result of applying the projection function to each value emitted on + * the output Observable and merging the results of the Observables obtained * from this transformation. */ export function expand>( diff --git a/src/internal/operators/filter.ts b/src/internal/operators/filter.ts index d8b420cd68..16bdcde5c6 100644 --- a/src/internal/operators/filter.ts +++ b/src/internal/operators/filter.ts @@ -48,6 +48,8 @@ export function filter(predicate: (value: T, index: number) => boolean): Mono * `0`. * @param thisArg An optional argument to determine the value of `this` * in the `predicate` function. + * @return A function that returns an Observable that emits items from the + * source Observable that satisfy the specified `predicate`. */ export function filter(predicate: (value: T, index: number) => boolean, thisArg?: any): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/finalize.ts b/src/internal/operators/finalize.ts index cded44f807..4602f79045 100644 --- a/src/internal/operators/finalize.ts +++ b/src/internal/operators/finalize.ts @@ -53,7 +53,8 @@ import { operate } from '../util/lift'; * ``` * * @param {function} callback Function to be called when source terminates. - * @return {Observable} An Observable that mirrors the source, but will call the specified function on termination. + * @return A function that returns an Observable that mirrors the source, but + * will call the specified function on termination. */ export function finalize(callback: () => void): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/find.ts b/src/internal/operators/find.ts index 35152da5d9..f97736fe80 100644 --- a/src/internal/operators/find.ts +++ b/src/internal/operators/find.ts @@ -51,8 +51,8 @@ export function find(predicate: (value: T, index: number, source: Observable< * A function called with each item to test for condition matching. * @param {any} [thisArg] An optional argument to determine the value of `this` * in the `predicate` function. - * @return {Observable} An Observable of the first item that matches the - * condition. + * @return A function that returns an Observable that emits the first item that + * matches the condition. */ export function find( predicate: (value: T, index: number, source: Observable) => boolean, diff --git a/src/internal/operators/findIndex.ts b/src/internal/operators/findIndex.ts index a19c7a0be0..7c476c5b0f 100644 --- a/src/internal/operators/findIndex.ts +++ b/src/internal/operators/findIndex.ts @@ -45,8 +45,8 @@ export function findIndex(predicate: (value: T, index: number, source: Observ * A function called with each item to test for condition matching. * @param {any} [thisArg] An optional argument to determine the value of `this` * in the `predicate` function. - * @return {Observable} An Observable of the index of the first item that - * matches the condition. + * @return A function that returns an Observable that emits the index of the + * first item that matches the condition. */ export function findIndex( predicate: (value: T, index: number, source: Observable) => boolean, diff --git a/src/internal/operators/first.ts b/src/internal/operators/first.ts index 43dc7703d3..e96bd7337a 100644 --- a/src/internal/operators/first.ts +++ b/src/internal/operators/first.ts @@ -70,8 +70,8 @@ export function first( * An optional function called with each item to test for condition matching. * @param {R} [defaultValue] The default value emitted in case no valid value * was found on the source. - * @return {Observable} An Observable of the first item that matches the - * condition. + * @return A function that returns an Observable that emits the first item that + * matches the condition. */ export function first( predicate?: ((value: T, index: number, source: Observable) => boolean) | null, diff --git a/src/internal/operators/groupBy.ts b/src/internal/operators/groupBy.ts index d7ffd001f1..bbe9d19296 100644 --- a/src/internal/operators/groupBy.ts +++ b/src/internal/operators/groupBy.ts @@ -110,10 +110,9 @@ export function groupBy( * exist. * @param {function(): Subject} [subjectSelector] Factory function to create an * intermediate Subject through which grouped elements are emitted. - * @return {Observable>} An Observable that emits - * GroupedObservables, each of which corresponds to a unique key value and each - * of which emits those items from the source Observable that share that key - * value. + * @return A function that returns an Observable that emits GroupedObservables, + * each of which corresponds to a unique key value and each of which emits + * those items from the source Observable that share that key value. */ export function groupBy( keySelector: (value: T) => K, diff --git a/src/internal/operators/ignoreElements.ts b/src/internal/operators/ignoreElements.ts index 1ecfeb7c57..d270749c4f 100644 --- a/src/internal/operators/ignoreElements.ts +++ b/src/internal/operators/ignoreElements.ts @@ -31,8 +31,9 @@ import { noop } from '../util/noop'; * // result: * // 'the end' * ``` - * @return {Observable} An empty Observable that only calls `complete` - * or `error`, based on which one is called by the source Observable. + * @return A function that returns an empty Observable that only calls + * `complete` or `error`, based on which one is called by the source + * Observable. */ export function ignoreElements(): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/isEmpty.ts b/src/internal/operators/isEmpty.ts index 42cb390bee..73ab44622a 100644 --- a/src/internal/operators/isEmpty.ts +++ b/src/internal/operators/isEmpty.ts @@ -62,7 +62,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link count} * @see {@link index/EMPTY} * - * @return {OperatorFunction} An Observable of a boolean value indicating whether observable was empty or not. + * @return A function that returns an Observable that emits boolean value + * indicating whether the source Observable was empty or not. */ export function isEmpty(): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/last.ts b/src/internal/operators/last.ts index ad8803a447..5117db061a 100644 --- a/src/internal/operators/last.ts +++ b/src/internal/operators/last.ts @@ -64,8 +64,9 @@ export function last( * @param {function} [predicate] - The condition any source emitted item has to satisfy. * @param {any} [defaultValue] - An optional default value to provide if last * predicate isn't met or no values were emitted. - * @return {Observable} An Observable that emits only the last item satisfying the given condition - * from the source, or an NoSuchElementException if no such items are emitted. + * @return A function that returns an Observable that emits only the last item + * satisfying the given condition from the source, or a NoSuchElementException + * if no such items are emitted. * @throws - Throws if no items that match the predicate are emitted by the source Observable. */ export function last( diff --git a/src/internal/operators/map.ts b/src/internal/operators/map.ts index 502b87ac98..6261392007 100644 --- a/src/internal/operators/map.ts +++ b/src/internal/operators/map.ts @@ -39,8 +39,8 @@ export function map(project: (this: A, value: T, index: number) => R, t * subscription, starting from the number `0`. * @param {any} [thisArg] An optional argument to define what `this` is in the * `project` function. - * @return {Observable} An Observable that emits the values from the source - * Observable transformed by the given `project` function. + * @return A function that returns an Observable that emits the values from the + * source Observable transformed by the given `project` function. */ export function map(project: (value: T, index: number) => R, thisArg?: any): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/mapTo.ts b/src/internal/operators/mapTo.ts index 0aea38935c..33c341dd5c 100644 --- a/src/internal/operators/mapTo.ts +++ b/src/internal/operators/mapTo.ts @@ -33,8 +33,8 @@ export function mapTo(value: R): OperatorFunction; * @see {@link map} * * @param {any} value The value to map each source value to. - * @return {Observable} An Observable that emits the given `value` every time - * the source Observable emits something. + * @return A function that returns an Observable that emits the given `value` + * every time the source Observable emits. */ export function mapTo(value: R): OperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/materialize.ts b/src/internal/operators/materialize.ts index 6501adfbae..f9be446323 100644 --- a/src/internal/operators/materialize.ts +++ b/src/internal/operators/materialize.ts @@ -49,9 +49,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link Notification} * @see {@link dematerialize} * - * @return {Observable>} An Observable that emits - * {@link Notification} objects that wrap the original emissions from the source - * Observable with metadata. + * @return A function that returns an Observable that emits + * {@link Notification} objects that wrap the original emissions from the + * source Observable with metadata. * * @deprecated In version 8, materialize will start to emit {@link ObservableNotification} objects, and not * {@link Notification} instances. This means that methods that are not commonly used, like `Notification.observe` diff --git a/src/internal/operators/max.ts b/src/internal/operators/max.ts index f6ab057744..744ff8ea5e 100644 --- a/src/internal/operators/max.ts +++ b/src/internal/operators/max.ts @@ -43,7 +43,8 @@ import { isFunction } from '../util/isFunction'; * * @param {Function} [comparer] - Optional comparer function that it will use instead of its default to compare the * value of two items. - * @return {Observable} An Observable that emits item with the largest value. + * @return A function that returns an Observable that emits item with the + * largest value. */ export function max(comparer?: (x: T, y: T) => number): MonoTypeOperatorFunction { return reduce(isFunction(comparer) ? (x, y) => (comparer(x, y) > 0 ? x : y) : (x, y) => (x > y ? x : y)); diff --git a/src/internal/operators/mergeAll.ts b/src/internal/operators/mergeAll.ts index 35c3ad07d5..c5fb539ff9 100644 --- a/src/internal/operators/mergeAll.ts +++ b/src/internal/operators/mergeAll.ts @@ -55,8 +55,8 @@ import { OperatorFunction, ObservableInput, ObservedValueOf } from '../types'; * * @param {number} [concurrent=Infinity] Maximum number of inner * Observables being subscribed to concurrently. - * @return {Observable} An Observable that emits values coming from all the - * inner Observables emitted by the source Observable. + * @return A function that returns an Observable that emits values coming from + * all the inner Observables emitted by the source Observable. */ export function mergeAll>(concurrent: number = Infinity): OperatorFunction> { return mergeMap(identity, concurrent); diff --git a/src/internal/operators/mergeMap.ts b/src/internal/operators/mergeMap.ts index 089f82830b..cb98fc025e 100644 --- a/src/internal/operators/mergeMap.ts +++ b/src/internal/operators/mergeMap.ts @@ -73,10 +73,10 @@ export function mergeMap>( * Observable. * @param {number} [concurrent=Infinity] Maximum number of input * Observables being subscribed to concurrently. - * @return {Observable} An Observable that emits the result of applying the - * projection function (and the optional deprecated `resultSelector`) to each item - * emitted by the source Observable and merging the results of the Observables - * obtained from this transformation. + * @return A function that returns an Observable that emits the result of + * applying the projection function (and the optional deprecated + * `resultSelector`) to each item emitted by the source Observable and merging + * the results of the Observables obtained from this transformation. */ export function mergeMap>( project: (value: T, index: number) => O, diff --git a/src/internal/operators/mergeMapTo.ts b/src/internal/operators/mergeMapTo.ts index 57c4725adf..76d4e96c95 100644 --- a/src/internal/operators/mergeMapTo.ts +++ b/src/internal/operators/mergeMapTo.ts @@ -43,14 +43,14 @@ export function mergeMapTo>(innerObserv * the source Observable. * @param {number} [concurrent=Infinity] Maximum number of input * Observables being subscribed to concurrently. - * @return {Observable} An Observable that emits items from the given - * `innerObservable` + * @return A function that returns an Observable that emits items from the + * given `innerObservable`. */ export function mergeMapTo>( innerObservable: O, resultSelector?: ((outerValue: T, innerValue: ObservedValueOf, outerIndex: number, innerIndex: number) => R) | number, concurrent: number = Infinity -): OperatorFunction|R> { +): OperatorFunction | R> { if (isFunction(resultSelector)) { return mergeMap(() => innerObservable, resultSelector, concurrent); } diff --git a/src/internal/operators/mergeScan.ts b/src/internal/operators/mergeScan.ts index 592b10ed20..2479062a63 100644 --- a/src/internal/operators/mergeScan.ts +++ b/src/internal/operators/mergeScan.ts @@ -40,7 +40,7 @@ import { mergeInternals } from './mergeInternals'; * @param seed The initial accumulation value. * @param {number} [concurrent=Infinity] Maximum number of * input Observables being subscribed to concurrently. - * @return {Observable} An observable of the accumulated values. + * @return A function that returns an Observable of the accumulated values. */ export function mergeScan( accumulator: (acc: R, value: T, index: number) => ObservableInput, diff --git a/src/internal/operators/mergeWith.ts b/src/internal/operators/mergeWith.ts index e66b556184..8046e141e2 100644 --- a/src/internal/operators/mergeWith.ts +++ b/src/internal/operators/mergeWith.ts @@ -39,6 +39,8 @@ import { merge } from './merge'; * // "dblclick" * ``` * @param otherSources the sources to combine the current source with. + * @return A function that returns an Observable that merges the values from + * all given Observables. */ export function mergeWith( ...otherSources: [...ObservableInputTuple] diff --git a/src/internal/operators/min.ts b/src/internal/operators/min.ts index bae2272d37..8a8058f862 100644 --- a/src/internal/operators/min.ts +++ b/src/internal/operators/min.ts @@ -42,7 +42,8 @@ import { isFunction } from '../util/isFunction'; * * @param {Function} [comparer] - Optional comparer function that it will use instead of its default to compare the * value of two items. - * @return {Observable} An Observable that emits item with the smallest value. + * @return A function that returns an Observable that emits item with the + * smallest value. */ export function min(comparer?: (x: T, y: T) => number): MonoTypeOperatorFunction { return reduce(isFunction(comparer) ? (x, y) => (comparer(x, y) < 0 ? x : y) : (x, y) => (x < y ? x : y)); diff --git a/src/internal/operators/multicast.ts b/src/internal/operators/multicast.ts index f8d54f0b72..f831bcf536 100644 --- a/src/internal/operators/multicast.ts +++ b/src/internal/operators/multicast.ts @@ -11,6 +11,7 @@ import { connect } from './connect'; * from the source to all consumers. * * @param subject The subject to multicast through. + * @return A function that returns a {@link ConnectableObservable} * @deprecated This will be removed in version 8. Please use the {@link connectable} creation * function, which creates a connectable observable. If you were using the {@link refCount} operator * on the result of the `multicast` operator, then use the {@link share} operator, which is now @@ -26,6 +27,7 @@ export function multicast(subject: Subject): UnaryFunction, * * @param subject The subject used to multicast. * @param selector A setup function to setup the multicast + * @return A function that returns an observable that mirrors the observable returned by the selector. * @deprecated To be removed in version 8. Please use the new {@link connect} operator. * `multicast(subject, fn)` is equivalent to `connect({ connector: () => subject, setup: fn })`. */ @@ -42,6 +44,7 @@ export function multicast>( * @param subjectFactory A factory that will be called to create the subject. Passing a function here * will cause the underlying subject to be "reset" on error, completion, or refCounted unsubscription of * the source. + * @return A function that returns a {@link ConnectableObservable} * @deprecated This will be removed in version 8. Please use the {@link connectable} creation * function, which creates a connectable observable. If you were using the {@link refCount} operator * on the result of the `multicast` operator, then use the {@link share} operator, which is now @@ -57,6 +60,7 @@ export function multicast(subjectFactory: () => Subject): UnaryFunction} Observable that emits the same notifications as the source Observable, - * but with provided scheduler. + * @return A function that returns an Observable that emits the same + * notifications as the source Observable, but with provided scheduler. */ export function observeOn(scheduler: SchedulerLike, delay: number = 0): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/onErrorResumeNext.ts b/src/internal/operators/onErrorResumeNext.ts index 804bc3c51c..28afb41627 100644 --- a/src/internal/operators/onErrorResumeNext.ts +++ b/src/internal/operators/onErrorResumeNext.ts @@ -75,9 +75,10 @@ export function onErrorResumeNext( * @see {@link concat} * @see {@link catchError} * - * @param {...ObservableInput} observables Observables passed either directly or as an array. - * @return {Observable} An Observable that emits values from source Observable, but - if it errors - subscribes - * to the next passed Observable and so on, until it completes or runs out of Observables. + * @param {...ObservableInput} nextSources Observables passed either directly or as an array. + * @return A function that returns an Observable that emits values from source + * Observable, but - if it errors - subscribes to the next passed Observable + * and so on, until it completes or runs out of Observables. */ export function onErrorResumeNext( ...sources: [[...ObservableInputTuple]] | [...ObservableInputTuple] diff --git a/src/internal/operators/pairwise.ts b/src/internal/operators/pairwise.ts index cc252af72b..b040463563 100644 --- a/src/internal/operators/pairwise.ts +++ b/src/internal/operators/pairwise.ts @@ -40,7 +40,7 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link buffer} * @see {@link bufferCount} * - * @return {Observable>} An Observable of pairs (as arrays) of + * @return A function that returns an Observable of pairs (as arrays) of * consecutive values from the source Observable. */ export function pairwise(): OperatorFunction { diff --git a/src/internal/operators/partition.ts b/src/internal/operators/partition.ts index da642e7795..b1d45abf8e 100644 --- a/src/internal/operators/partition.ts +++ b/src/internal/operators/partition.ts @@ -44,9 +44,9 @@ import { UnaryFunction } from '../types'; * happened since the subscription, starting from the number `0`. * @param {any} [thisArg] An optional argument to determine the value of `this` * in the `predicate` function. - * @return {[Observable, Observable]} An array with two Observables: one - * with values that passed the predicate, and another with values that did not - * pass the predicate. + * @return A function that returns an array with two Observables: one with + * values that passed the predicate, and another with values that did not pass + * the predicate. * @deprecated use `partition` static creation function instead */ export function partition(predicate: (value: T, index: number) => boolean, diff --git a/src/internal/operators/pluck.ts b/src/internal/operators/pluck.ts index 96733e5a53..a0a0cedece 100644 --- a/src/internal/operators/pluck.ts +++ b/src/internal/operators/pluck.ts @@ -40,7 +40,8 @@ export function pluck(...properties: string[]): OperatorFunction; * * @param properties The nested properties to pluck from each source * value. - * @return A new Observable of property values from the source values. + * @return A function that returns an Observable of property values from the + * source values. * @deprecated Remove in v8. Use {@link map} and optional chaining: `pluck('foo', 'bar')` is `map(x => x?.foo?.bar)`. */ export function pluck(...properties: Array): OperatorFunction { @@ -60,4 +61,4 @@ export function pluck(...properties: Array): Ope } return currentProp; }); -} \ No newline at end of file +} diff --git a/src/internal/operators/publish.ts b/src/internal/operators/publish.ts index 025e2ad6f0..ba796f6ad0 100644 --- a/src/internal/operators/publish.ts +++ b/src/internal/operators/publish.ts @@ -75,7 +75,8 @@ export function publish>(selector: (shared: Ob * @param {Function} [selector] - Optional selector function which can use the multicasted source sequence as many times * as needed, without causing multiple subscriptions to the source sequence. * Subscribers to the given source will receive all notifications of the source from the time of the subscription on. - * @return A ConnectableObservable that upon connection causes the source Observable to emit items to its Observers. + * @return A function that returns a ConnectableObservable that upon connection + * causes the source Observable to emit items to its Observers. */ export function publish(selector?: OperatorFunction): MonoTypeOperatorFunction | OperatorFunction { return selector ? connect(selector) : multicast(new Subject()); diff --git a/src/internal/operators/publishBehavior.ts b/src/internal/operators/publishBehavior.ts index 7aa1dd4a7c..d0a581b6b2 100644 --- a/src/internal/operators/publishBehavior.ts +++ b/src/internal/operators/publishBehavior.ts @@ -7,7 +7,7 @@ import { UnaryFunction } from '../types'; * Creates a {@link ConnectableObservable} that utilizes a {@link BehaviorSubject}. * * @param initialValue The initial value passed to the {@link BehaviorSubject}. - * @return {ConnectableObservable} + * @return A function that returns a {@link ConnectableObservable} * @deprecated to be removed in version 8. If you want to get a connectable observable that uses a * {@link BehaviorSubject} under the hood, please use {@link connectable}. `source.pipe(publishBehavior(initValue))` * is equivalent to: `connectable(source, () => new BehaviorSubject(initValue))`. diff --git a/src/internal/operators/publishLast.ts b/src/internal/operators/publishLast.ts index d279e1c888..0d65444103 100644 --- a/src/internal/operators/publishLast.ts +++ b/src/internal/operators/publishLast.ts @@ -50,7 +50,12 @@ import { UnaryFunction } from '../types'; * // "Sub. B Complete" * ``` * - * @return A connectable observable sequence that contains the elements of a + * @see {@link ConnectableObservable} + * @see {@link publish} + * @see {@link publishReplay} + * @see {@link publishBehavior} + * + * @return A function that returns an Observable that emits elements of a * sequence produced by multicasting the source sequence. * @deprecated To be removed in version 8. If you're trying to create a connectable observable * with an {@link AsyncSubject} under the hood, please use the new {@link connectable} creation function. diff --git a/src/internal/operators/race.ts b/src/internal/operators/race.ts index 879b577d07..a31e3649ee 100644 --- a/src/internal/operators/race.ts +++ b/src/internal/operators/race.ts @@ -10,8 +10,9 @@ export function race(...otherSources: [...Obser /** * Returns an Observable that mirrors the first source Observable to emit a next, * error or complete notification from the combination of this Observable and supplied Observables. - * @param {...Observables} ...observables Sources used to race for which Observable emits first. - * @return {Observable} An Observable that mirrors the output of the first Observable to emit an item. + * @param args Sources used to race for which Observable emits first. + * @return A function that returns an Observable that mirrors the output of the + * first Observable to emit an item. * @deprecated Deprecated use {@link raceWith} */ export function race(...args: any[]): OperatorFunction { diff --git a/src/internal/operators/raceWith.ts b/src/internal/operators/raceWith.ts index 8b20857074..3953fa55cf 100644 --- a/src/internal/operators/raceWith.ts +++ b/src/internal/operators/raceWith.ts @@ -29,6 +29,8 @@ import { identity } from '../util/identity'; * ``` * * @param otherSources Sources used to race for which Observable emits first. + * @return A function that returns an Observable that mirrors the output of the + * first Observable to emit an item. */ export function raceWith( diff --git a/src/internal/operators/reduce.ts b/src/internal/operators/reduce.ts index f5b3ed3433..9ff5de8566 100644 --- a/src/internal/operators/reduce.ts +++ b/src/internal/operators/reduce.ts @@ -52,8 +52,8 @@ export function reduce(accumulator: (acc: A | S, value: V, index: n * @param {function(acc: A, value: V, index: number): A} accumulator The accumulator function * called on each source value. * @param {A} [seed] The initial accumulation value. - * @return {Observable} An Observable that emits a single value that is the - * result of accumulating the values emitted by the source Observable. + * @return A function that returns an Observable that emits a single value that + * is the result of accumulating the values emitted by the source Observable. */ export function reduce(accumulator: (acc: V | A, value: V, index: number) => A, seed?: any): OperatorFunction { return operate(scanInternals(accumulator, seed, arguments.length >= 2, false, true)); diff --git a/src/internal/operators/refCount.ts b/src/internal/operators/refCount.ts index b56655551c..b955b82f41 100644 --- a/src/internal/operators/refCount.ts +++ b/src/internal/operators/refCount.ts @@ -53,6 +53,11 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * // Nothing happens until you call .connect() on the observable. * ``` * + * @return A function that returns an Observable that automates the connection + * to ConnectableObservable. + * @see {@link ConnectableObservable} + * @see {@link share} + * @see {@link publish} * @deprecated to be removed in version 8. Use the updated {@link share} operator, * which now is highly configurable. How `share` is used will depend on the connectable * observable you created just prior to the `refCount` operator. For examples on how diff --git a/src/internal/operators/repeat.ts b/src/internal/operators/repeat.ts index 0bd721156f..1b1da315da 100644 --- a/src/internal/operators/repeat.ts +++ b/src/internal/operators/repeat.ts @@ -55,8 +55,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param {number} [count] The number of times the source Observable items are repeated, a count of 0 will yield * an empty Observable. - * @return {Observable} An Observable that will resubscribe to the source stream when the source stream completes - * , at most count times. + * @return A function that returns an Observable that will resubscribe to the + * source stream when the source stream completes, at most `count` times. */ export function repeat(count = Infinity): MonoTypeOperatorFunction { return count <= 0 diff --git a/src/internal/operators/repeatWhen.ts b/src/internal/operators/repeatWhen.ts index b6fd798513..05b122c3dd 100644 --- a/src/internal/operators/repeatWhen.ts +++ b/src/internal/operators/repeatWhen.ts @@ -32,7 +32,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param {function(notifications: Observable): Observable} notifier - Receives an Observable of notifications with * which a user can `complete` or `error`, aborting the repetition. - * @return {Observable} The source Observable modified with repeat logic. + * @return A function that returns an Observable that that mirrors the source + * Observable with the exception of a `complete`. */ export function repeatWhen(notifier: (notifications: Observable) => Observable): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/retry.ts b/src/internal/operators/retry.ts index 22aed00319..1e892d8ba8 100644 --- a/src/internal/operators/retry.ts +++ b/src/internal/operators/retry.ts @@ -52,7 +52,8 @@ export interface RetryConfig { * * @param {number} count - Number of retry attempts before failing. * @param {boolean} resetOnSuccess - When set to `true` every successful emission will reset the error count - * @return {Observable} The source Observable modified with the retry logic. + * @return A function that returns an Observable that will resubscribe to the + * source stream when the source stream errors, at most `count` times. */ export function retry(count?: number): MonoTypeOperatorFunction; export function retry(config: RetryConfig): MonoTypeOperatorFunction; diff --git a/src/internal/operators/retryWhen.ts b/src/internal/operators/retryWhen.ts index a00a10aa68..347d0e36f0 100644 --- a/src/internal/operators/retryWhen.ts +++ b/src/internal/operators/retryWhen.ts @@ -55,7 +55,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param {function(errors: Observable): Observable} notifier - Receives an Observable of notifications with which a * user can `complete` or `error`, aborting the retry. - * @return {Observable} The source Observable modified with retry logic. + * @return A function that returns an Observable that mirrors the source + * Observable with the exception of an `error`. */ export function retryWhen(notifier: (errors: Observable) => Observable): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/sample.ts b/src/internal/operators/sample.ts index 0bc3cceff5..cee3ca9619 100644 --- a/src/internal/operators/sample.ts +++ b/src/internal/operators/sample.ts @@ -36,11 +36,11 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link sampleTime} * @see {@link throttle} * - * @param {Observable} notifier The Observable to use for sampling the + * @param notifier The Observable to use for sampling the * source Observable. - * @return {Observable} An Observable that emits the results of sampling the - * values emitted by the source Observable whenever the notifier Observable - * emits value. + * @return A function that returns an Observable that emits the results of + * sampling the values emitted by the source Observable whenever the notifier + * Observable emits value or completes. */ export function sample(notifier: Observable): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/sampleTime.ts b/src/internal/operators/sampleTime.ts index 0eb4d6fd20..85ffa32eb4 100644 --- a/src/internal/operators/sampleTime.ts +++ b/src/internal/operators/sampleTime.ts @@ -40,8 +40,9 @@ import { interval } from '../observable/interval'; * time unit determined internally by the optional `scheduler`. * @param {SchedulerLike} [scheduler=async] The {@link SchedulerLike} to use for * managing the timers that handle the sampling. - * @return {Observable} An Observable that emits the results of sampling the - * values emitted by the source Observable at the specified time interval. + * @return A function that returns an Observable that emits the results of + * sampling the values emitted by the source Observable at the specified time + * interval. * @deprecated To be removed in v8. Use `sample(interval(period, scheduler?))`, it's the same thing. */ export function sampleTime(period: number, scheduler: SchedulerLike = asyncScheduler): MonoTypeOperatorFunction { diff --git a/src/internal/operators/scan.ts b/src/internal/operators/scan.ts index 5ac7958302..7365383743 100644 --- a/src/internal/operators/scan.ts +++ b/src/internal/operators/scan.ts @@ -86,6 +86,7 @@ export function scan(accumulator: (acc: A | S, value: V, index: number) * be used as the initial state, and emitted without going through the accumulator. All subsequent values * will be processed by the accumulator function. If this is provided, all values will go through * the accumulator function. + * @return A function that returns an Observable of the accumulated values. */ export function scan(accumulator: (acc: V | A | S, value: V, index: number) => A, seed?: S): OperatorFunction { // providing a seed of `undefined` *should* be valid and trigger diff --git a/src/internal/operators/sequenceEqual.ts b/src/internal/operators/sequenceEqual.ts index 278300472e..86fc1affd6 100644 --- a/src/internal/operators/sequenceEqual.ts +++ b/src/internal/operators/sequenceEqual.ts @@ -56,8 +56,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param {Observable} compareTo The observable sequence to compare the source sequence to. * @param {function} [comparator] An optional function to compare each value pair - * @return {Observable} An Observable of a single boolean value representing whether or not - * the values emitted by both observables were equal in sequence. + * @return A function that returns an Observable that emits a single boolean + * value representing whether or not the values emitted by the source + * Observable and provided Observable were equal in sequence. */ export function sequenceEqual( compareTo: Observable, diff --git a/src/internal/operators/share.ts b/src/internal/operators/share.ts index 25a0d4b263..d89d23ec6c 100644 --- a/src/internal/operators/share.ts +++ b/src/internal/operators/share.ts @@ -84,6 +84,12 @@ export function share(options: ShareConfig): MonoTypeOperatorFunction; * // subscription 1: 9 * // ... and so on * ``` + * + * @see {@link api/index/function/interval} + * @see {@link map} + * + * @return A function that returns an Observable that upon connection causes + * the source Observable to emit items to its Observers. */ export function share(options?: ShareConfig): OperatorFunction { options = options || {}; diff --git a/src/internal/operators/shareReplay.ts b/src/internal/operators/shareReplay.ts index 66178b91d9..49c59e9314 100644 --- a/src/internal/operators/shareReplay.ts +++ b/src/internal/operators/shareReplay.ts @@ -115,8 +115,9 @@ export function shareReplay(bufferSize?: number, windowTime?: number, schedul * @param {Number} [windowTime=Infinity] Maximum time length of the replay buffer in milliseconds. * @param {Scheduler} [scheduler] Scheduler where connected observers within the selector function * will be invoked on. - * @return {Observable} An observable sequence that contains the elements of a sequence produced - * by multicasting the source sequence within a selector function. + * @return A function that returns an Observable sequence that contains the + * elements of a sequence produced by multicasting the source sequence within a + * selector function. */ export function shareReplay( configOrBufferSize?: ShareReplayConfig | number, diff --git a/src/internal/operators/single.ts b/src/internal/operators/single.ts index cb11fa4fc0..495f629148 100644 --- a/src/internal/operators/single.ts +++ b/src/internal/operators/single.ts @@ -87,8 +87,9 @@ export function single(predicate?: (value: T, index: number, source: Observab * provided predicate. If no predicate is provided, will deliver a SequenceError if more * that one value comes from the source * @param {Function} predicate - A predicate function to evaluate items emitted by the source Observable. - * @return {Observable} An Observable that emits the single item emitted by the source Observable that matches - * the predicate or `undefined` when no items match. + * @return A function that returns an Observable that emits the single item + * emitted by the source Observable that matches the predicate or `undefined` + * when no items match. */ export function single(predicate?: (value: T, index: number, source: Observable) => boolean): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/skip.ts b/src/internal/operators/skip.ts index 8d0a45f5f2..02f8fc0930 100644 --- a/src/internal/operators/skip.ts +++ b/src/internal/operators/skip.ts @@ -29,7 +29,8 @@ import { filter } from './filter'; * @see {@link skipLast} * * @param {Number} count - The number of times, items emitted by source Observable should be skipped. - * @return {Observable} An Observable that skips values emitted by the source Observable. + * @return A function that returns an Observable that skips the first `count` + * values emitted by the source Observable. */ export function skip(count: number): MonoTypeOperatorFunction { return filter((_, index) => count <= index); diff --git a/src/internal/operators/skipLast.ts b/src/internal/operators/skipLast.ts index ed9e5dc8a3..20e652920d 100644 --- a/src/internal/operators/skipLast.ts +++ b/src/internal/operators/skipLast.ts @@ -43,7 +43,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link take} * * @param skipCount Number of elements to skip from the end of the source Observable. - * @returns An Observable that skips the last count values emitted by the source Observable. + * @return A function that returns an Observable that skips the last `count` + * values emitted by the source Observable. */ export function skipLast(skipCount: number): MonoTypeOperatorFunction { return skipCount <= 0 diff --git a/src/internal/operators/skipUntil.ts b/src/internal/operators/skipUntil.ts index d9ee309c4a..eedbbc3e47 100644 --- a/src/internal/operators/skipUntil.ts +++ b/src/internal/operators/skipUntil.ts @@ -39,8 +39,9 @@ import { noop } from '../util/noop'; * * @param {Observable} notifier - The second Observable that has to emit an item before the source Observable's elements begin to * be mirrored by the resulting Observable. - * @return {Observable} An Observable that skips items from the source Observable until the second Observable emits - * an item, then emits the remaining items. + * @return A function that returns an Observable that skips items from the + * source Observable until the second Observable emits an item, then emits the + * remaining items. */ export function skipUntil(notifier: Observable): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/skipWhile.ts b/src/internal/operators/skipWhile.ts index c040e1104d..18367c15cc 100644 --- a/src/internal/operators/skipWhile.ts +++ b/src/internal/operators/skipWhile.ts @@ -44,8 +44,8 @@ export function skipWhile(predicate: (value: T, index: number) => boolean): M * @see {@link skipLast} * * @param {Function} predicate - A function to test each item emitted from the source Observable. - * @return {Observable} An Observable that begins emitting items emitted by the source Observable when the - * specified predicate becomes false. + * @return A function that returns an Observable that begins emitting items + * emitted by the source Observable when the specified predicate becomes false. */ export function skipWhile(predicate: (value: T, index: number) => boolean): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/startWith.ts b/src/internal/operators/startWith.ts index d5cab4ced5..5f68aaaa74 100644 --- a/src/internal/operators/startWith.ts +++ b/src/internal/operators/startWith.ts @@ -50,6 +50,8 @@ export function startWith(...values: A): * ``` * * @param values Items you want the modified Observable to emit first. + * @return A function that returns an Observable that synchronously emits + * provided values before subscribing to the source Observable. * * @see {@link endWith} * @see {@link finalize} diff --git a/src/internal/operators/subscribeOn.ts b/src/internal/operators/subscribeOn.ts index 8201fdd675..0e90593221 100644 --- a/src/internal/operators/subscribeOn.ts +++ b/src/internal/operators/subscribeOn.ts @@ -58,7 +58,8 @@ import { operate } from '../util/lift'; * * @param scheduler The {@link SchedulerLike} to perform subscription actions on. * @param delay A delay to pass to the scheduler to delay subscriptions - * @return The source Observable modified so that its subscriptions happen on the specified {@link SchedulerLike}. + * @return A function that returns an Observable modified so that its + * subscriptions happen on the specified {@link SchedulerLike}. */ export function subscribeOn(scheduler: SchedulerLike, delay: number = 0): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/switchAll.ts b/src/internal/operators/switchAll.ts index 8f5e3f3ffc..7ab8fd020e 100644 --- a/src/internal/operators/switchAll.ts +++ b/src/internal/operators/switchAll.ts @@ -55,6 +55,10 @@ import { identity } from '../util/identity'; * @see {@link switchMap} * @see {@link switchMapTo} * @see {@link mergeAll} + * + * @return A function that returns an Observable that converts a higher-order + * Observable into a first-order Observable producing values only from the most + * recent Observable sequence. */ export function switchAll>(): OperatorFunction> { diff --git a/src/internal/operators/switchMap.ts b/src/internal/operators/switchMap.ts index 53b658c232..8c4a988018 100644 --- a/src/internal/operators/switchMap.ts +++ b/src/internal/operators/switchMap.ts @@ -75,10 +75,10 @@ export function switchMap>( * @param {function(value: T, ?index: number): ObservableInput} project A function * that, when applied to an item emitted by the source Observable, returns an * Observable. - * @return {Observable} An Observable that emits the result of applying the - * projection function (and the optional deprecated `resultSelector`) to each item - * emitted by the source Observable and taking only the values from the most recently - * projected inner Observable. + * @return A function that returns an Observable that emits the result of + * applying the projection function (and the optional deprecated + * `resultSelector`) to each item emitted by the source Observable and taking + * only the values from the most recently projected inner Observable. */ export function switchMap>( project: (value: T, index: number) => O, diff --git a/src/internal/operators/switchMapTo.ts b/src/internal/operators/switchMapTo.ts index 20edd8f4ca..215ca1288b 100644 --- a/src/internal/operators/switchMapTo.ts +++ b/src/internal/operators/switchMapTo.ts @@ -49,10 +49,11 @@ export function switchMapTo>( * * @param {ObservableInput} innerObservable An Observable to replace each value from * the source Observable. - * @return {Observable} An Observable that emits items from the given - * `innerObservable` (and optionally transformed through the deprecated `resultSelector`) - * every time a value is emitted on the source Observable, and taking only the values - * from the most recently projected inner Observable. + * @return A function that returns an Observable that emits items from the + * given `innerObservable` (and optionally transformed through the deprecated + * `resultSelector`) every time a value is emitted on the source Observable, + * and taking only the values from the most recently projected inner + * Observable. */ export function switchMapTo>( innerObservable: O, diff --git a/src/internal/operators/switchScan.ts b/src/internal/operators/switchScan.ts index e1c5feb6ef..c213665aed 100644 --- a/src/internal/operators/switchScan.ts +++ b/src/internal/operators/switchScan.ts @@ -19,7 +19,7 @@ import { operate } from '../util/lift'; * @param accumulator * The accumulator function called on each source value. * @param seed The initial accumulation value. - * @return An observable of the accumulated values. + * @return A function that returns an observable of the accumulated values. */ export function switchScan>( accumulator: (acc: R, value: T, index: number) => O, diff --git a/src/internal/operators/take.ts b/src/internal/operators/take.ts index dcfef1700d..e8bc9ba931 100644 --- a/src/internal/operators/take.ts +++ b/src/internal/operators/take.ts @@ -40,9 +40,9 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @see {@link skip} * * @param count The maximum number of `next` values to emit. - * @return An Observable that emits only the first `count` - * values emitted by the source Observable, or all of the values from the source - * if the source emits fewer than `count` values. + * @return A function that returns an Observable that emits only the first + * `count` values emitted by the source Observable, or all of the values from + * the source if the source emits fewer than `count` values. */ export function take(count: number): MonoTypeOperatorFunction { return count <= 0 diff --git a/src/internal/operators/takeLast.ts b/src/internal/operators/takeLast.ts index 368af348b7..b4ba0a97b9 100644 --- a/src/internal/operators/takeLast.ts +++ b/src/internal/operators/takeLast.ts @@ -40,8 +40,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * * @param count The maximum number of values to emit from the end of * the sequence of values emitted by the source Observable. - * @return An Observable that emits at most the last count - * values emitted by the source Observable. + * @return A function that returns an Observable that emits at most the last + * `count` values emitted by the source Observable. */ export function takeLast(count: number): MonoTypeOperatorFunction { return count <= 0 diff --git a/src/internal/operators/takeUntil.ts b/src/internal/operators/takeUntil.ts index 70941e9293..9835ee1309 100644 --- a/src/internal/operators/takeUntil.ts +++ b/src/internal/operators/takeUntil.ts @@ -39,8 +39,8 @@ import { noop } from '../util/noop'; * @param {Observable} notifier The Observable whose first emitted value will * cause the output Observable of `takeUntil` to stop emitting values from the * source Observable. - * @return {Observable} An Observable that emits the values from the source - * Observable until such time as `notifier` emits its first value. + * @return A function that returns an Observable that emits the values from the + * source Observable until `notifier` emits its first value. */ export function takeUntil(notifier: ObservableInput): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/takeWhile.ts b/src/internal/operators/takeWhile.ts index 07477e13bb..1ae3f0e8c0 100644 --- a/src/internal/operators/takeWhile.ts +++ b/src/internal/operators/takeWhile.ts @@ -50,9 +50,9 @@ export function takeWhile(predicate: (value: T, index: number) => boolean, in * Also takes the (zero-based) index as the second argument. * @param {boolean} inclusive When set to `true` the value that caused * `predicate` to return `false` will also be emitted. - * @return {Observable} An Observable that emits the values from the source - * Observable so long as each value satisfies the condition defined by the - * `predicate`, then completes. + * @return A function that returns an Observable that emits values from the + * source Observable so long as each value satisfies the condition defined by + * the `predicate`, then completes. */ export function takeWhile(predicate: (value: T, index: number) => boolean, inclusive = false): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/tap.ts b/src/internal/operators/tap.ts index 7f7e186382..e26366da87 100644 --- a/src/internal/operators/tap.ts +++ b/src/internal/operators/tap.ts @@ -104,6 +104,8 @@ export function tap(observer: PartialObserver): MonoTypeOperatorFunction( observerOrNext?: PartialObserver | ((value: T) => void) | null, diff --git a/src/internal/operators/throttle.ts b/src/internal/operators/throttle.ts index d8c221d6a0..99cfa5f965 100644 --- a/src/internal/operators/throttle.ts +++ b/src/internal/operators/throttle.ts @@ -56,8 +56,8 @@ export const defaultThrottleConfig: ThrottleConfig = { * duration for each source value, returned as an Observable or a Promise. * @param config a configuration object to define `leading` and `trailing` behavior. Defaults * to `{ leading: true, trailing: false }`. - * @return An Observable that performs the throttle operation to - * limit the rate of emissions from the source. + * @return A function that returns an Observable that performs the throttle + * operation to limit the rate of emissions from the source. */ export function throttle( durationSelector: (value: T) => ObservableInput, diff --git a/src/internal/operators/throttleTime.ts b/src/internal/operators/throttleTime.ts index a558ab821a..8dc17e6f9f 100644 --- a/src/internal/operators/throttleTime.ts +++ b/src/internal/operators/throttleTime.ts @@ -77,8 +77,8 @@ import { timer } from '../observable/timer'; * managing the timers that handle the throttling. Defaults to {@link asyncScheduler}. * @param config a configuration object to define `leading` and * `trailing` behavior. Defaults to `{ leading: true, trailing: false }`. - * @return An Observable that performs the throttle operation to - * limit the rate of emissions from the source. + * @return A function that returns an Observable that performs the throttle + * operation to limit the rate of emissions from the source. */ export function throttleTime( duration: number, diff --git a/src/internal/operators/throwIfEmpty.ts b/src/internal/operators/throwIfEmpty.ts index dad77a3030..cf53be1795 100644 --- a/src/internal/operators/throwIfEmpty.ts +++ b/src/internal/operators/throwIfEmpty.ts @@ -32,6 +32,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * @param errorFactory A factory function called to produce the * error to be thrown when the source observable completes without emitting a * value. + * @return A function that returns an Observable that throws an error if the + * source Observable completed without emitting. */ export function throwIfEmpty(errorFactory: () => any = defaultErrorFactory): MonoTypeOperatorFunction { return operate((source, subscriber) => { diff --git a/src/internal/operators/timeInterval.ts b/src/internal/operators/timeInterval.ts index ee021e7f5d..dc19014196 100644 --- a/src/internal/operators/timeInterval.ts +++ b/src/internal/operators/timeInterval.ts @@ -47,7 +47,8 @@ import { map } from './map'; * ``` * * @param {SchedulerLike} [scheduler] Scheduler used to get the current time. - * @return {Observable<{ interval: number, value: T }>} Observable that emit infomation about value and interval + * @return A function that returns an Observable that emits information about + * value and interval. */ export function timeInterval(scheduler: SchedulerLike = async): OperatorFunction> { return (source: Observable) => defer(() => { diff --git a/src/internal/operators/timeout.ts b/src/internal/operators/timeout.ts index b21fccd819..47a35d1eef 100644 --- a/src/internal/operators/timeout.ts +++ b/src/internal/operators/timeout.ts @@ -299,6 +299,9 @@ export function timeout(each: number, scheduler?: SchedulerLike): MonoTypeOpe * Timeouts on Observable that doesn't emit values fast enough. * * ![](timeout.png) + * + * @return A function that returns an Observable that mirrors behaviour of the + * source Observable, unless timeout happens when it throws an error. */ export function timeout, M>( config: number | Date | TimeoutConfig, diff --git a/src/internal/operators/timeoutWith.ts b/src/internal/operators/timeoutWith.ts index bbb26694cd..f51596754e 100644 --- a/src/internal/operators/timeoutWith.ts +++ b/src/internal/operators/timeoutWith.ts @@ -76,6 +76,9 @@ export function timeoutWith(dueBy: Date, switchTo: ObservableInput, sch * @param waitFor The time allowed between values from the source before timeout is triggered. * @param switchTo The observable to switch to when timeout occurs. * @param scheduler The scheduler to use with time-related operations within this operator. Defaults to {@link asyncScheduler} + * @return A function that returns an Observable that mirrors behaviour of the + * source Observable, unless timeout happens when it starts emitting values + * from the Observable passed as a second parameter. * @deprecated This will be removed in v8. Use the configuration object with {@link timeout} instead: `timeoutWith(100, a$, scheduler)` -> `timeout({ each: 100, with: () => a$, scheduler })` */ export function timeoutWith(waitFor: number, switchTo: ObservableInput, scheduler?: SchedulerLike): OperatorFunction; diff --git a/src/internal/operators/timestamp.ts b/src/internal/operators/timestamp.ts index ba1ea39d5e..efecad7fb2 100644 --- a/src/internal/operators/timestamp.ts +++ b/src/internal/operators/timestamp.ts @@ -32,7 +32,9 @@ import { map } from './map'; * ``` * * @param timestampProvider An object with a `now()` method used to get the current timestamp. + * @return A function that returns an Observable that attaches a timestamp to + * each item emitted by the source Observable indicating when it was emitted. */ export function timestamp(timestampProvider: TimestampProvider = dateTimestampProvider): OperatorFunction> { return map((value: T) => ({ value, timestamp: timestampProvider.now()})); -} \ No newline at end of file +} diff --git a/src/internal/operators/toArray.ts b/src/internal/operators/toArray.ts index e4cff7951e..bab880281f 100644 --- a/src/internal/operators/toArray.ts +++ b/src/internal/operators/toArray.ts @@ -29,10 +29,11 @@ const arrReducer = (arr: any[], value: any) => (arr.push(value), arr); * const subscribe = example.subscribe(val => console.log(val)); * * // output: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] - * * ``` -* @return An array from an observable sequence. -*/ + * + * @return A function that returns an Observable that emits an array of items + * emitted by the source Observable when source completes. + */ export function toArray(): OperatorFunction { // Because arrays are mutable, and we're mutating the array in this // reducer process, we have to escapulate the creation of the initial diff --git a/src/internal/operators/window.ts b/src/internal/operators/window.ts index 8671a2a7cb..58c1b5f0f6 100644 --- a/src/internal/operators/window.ts +++ b/src/internal/operators/window.ts @@ -43,7 +43,7 @@ import { noop } from '../util/noop'; * * @param {Observable} windowBoundaries An Observable that completes the * previous window and starts a new window. - * @return {Observable>} An Observable of windows, which are + * @return A function that returns an Observable of windows, which are * Observables emitting values of the source Observable. */ export function window(windowBoundaries: Observable): OperatorFunction> { diff --git a/src/internal/operators/windowCount.ts b/src/internal/operators/windowCount.ts index bc957216b6..b32839a107 100644 --- a/src/internal/operators/windowCount.ts +++ b/src/internal/operators/windowCount.ts @@ -62,8 +62,8 @@ import { OperatorSubscriber } from './OperatorSubscriber'; * For example if `startWindowEvery` is `2`, then a new window will be started * on every other value from the source. A new window is started at the * beginning of the source by default. - * @return {Observable>} An Observable of windows, which in turn - * are Observable of values. + * @return A function that returns an Observable of windows, which in turn are + * Observable of values. */ export function windowCount(windowSize: number, startWindowEvery: number = 0): OperatorFunction> { const startEvery = startWindowEvery > 0 ? startWindowEvery : windowSize; diff --git a/src/internal/operators/windowTime.ts b/src/internal/operators/windowTime.ts index d1622c713b..f37fbb6171 100644 --- a/src/internal/operators/windowTime.ts +++ b/src/internal/operators/windowTime.ts @@ -97,7 +97,8 @@ export function windowTime( * values each window can emit before completion. * @param scheduler The scheduler on which to schedule the * intervals that determine window boundaries. - * @return An observable of windows, which in turn are Observables. + * @return A function that returns an Observable of windows, which in turn are + * Observables. */ export function windowTime(windowTimeSpan: number, ...otherArgs: any[]): OperatorFunction> { const scheduler = popScheduler(otherArgs) ?? asyncScheduler; diff --git a/src/internal/operators/windowToggle.ts b/src/internal/operators/windowToggle.ts index 256bee5b6c..2c92c1208b 100644 --- a/src/internal/operators/windowToggle.ts +++ b/src/internal/operators/windowToggle.ts @@ -51,8 +51,8 @@ import { arrRemove } from '../util/arrRemove'; * the value emitted by the `openings` observable and returns an Observable, * which, when it emits a next notification, signals that the * associated window should complete. - * @return {Observable>} An observable of windows, which in turn - * are Observables. + * @return A function that returns an Observable of windows, which in turn are + * Observables. */ export function windowToggle( openings: ObservableInput, diff --git a/src/internal/operators/windowWhen.ts b/src/internal/operators/windowWhen.ts index 1eac1e63e4..e3aaf1738a 100644 --- a/src/internal/operators/windowWhen.ts +++ b/src/internal/operators/windowWhen.ts @@ -46,8 +46,8 @@ import { innerFrom } from '../observable/from'; * @param {function(): Observable} closingSelector A function that takes no * arguments and returns an Observable that signals (on either `next` or * `complete`) when to close the previous window and start a new one. - * @return {Observable>} An observable of windows, which in turn - * are Observables. + * @return A function that returns an Observable of windows, which in turn are + * Observables. */ export function windowWhen(closingSelector: () => ObservableInput): OperatorFunction> { return operate((source, subscriber) => { diff --git a/src/internal/operators/withLatestFrom.ts b/src/internal/operators/withLatestFrom.ts index 4366ac7915..8d503e1b35 100644 --- a/src/internal/operators/withLatestFrom.ts +++ b/src/internal/operators/withLatestFrom.ts @@ -50,9 +50,9 @@ export function withLatestFrom( * first parameter is a value from the source Observable. (e.g. * `a.pipe(withLatestFrom(b, c), map(([a1, b1, c1]) => a1 + b1 + c1))`). If this is not * passed, arrays will be emitted on the output Observable. - * @return {Observable} An Observable of projected values from the most recent - * values from each input Observable, or an array of the most recent values from - * each input Observable. + * @return A function that returns an Observable of projected values from the + * most recent values from each input Observable, or an array of the most + * recent values from each input Observable. */ export function withLatestFrom(...inputs: any[]): OperatorFunction { const project = popResultSelector(inputs) as ((...args: any[]) => R) | undefined; diff --git a/src/internal/operators/zipWith.ts b/src/internal/operators/zipWith.ts index 56a42b6ca6..22eaad7938 100644 --- a/src/internal/operators/zipWith.ts +++ b/src/internal/operators/zipWith.ts @@ -20,6 +20,9 @@ import { zip } from './zip'; * In many cases, authors want `combineLatestWith` and not `zipWith`. * * @param otherInputs other observable inputs to collate values from. + * @return A function that returns an Observable that emits items by index + * combined from the source Observable and provided Observables, in form of an + * array. */ export function zipWith(...otherInputs: [...ObservableInputTuple]): OperatorFunction> { return zip(...otherInputs); From 51e64c67051e43502aa02fea91304640518be95b Mon Sep 17 00:00:00 2001 From: Nicholas Jamieson Date: Wed, 17 Mar 2021 17:01:06 +1000 Subject: [PATCH 2/3] docs: single will not emit undefined --- src/internal/operators/single.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/internal/operators/single.ts b/src/internal/operators/single.ts index 495f629148..1ecdc4c391 100644 --- a/src/internal/operators/single.ts +++ b/src/internal/operators/single.ts @@ -88,8 +88,7 @@ export function single(predicate?: (value: T, index: number, source: Observab * that one value comes from the source * @param {Function} predicate - A predicate function to evaluate items emitted by the source Observable. * @return A function that returns an Observable that emits the single item - * emitted by the source Observable that matches the predicate or `undefined` - * when no items match. + * emitted by the source Observable that matches the predicate. */ export function single(predicate?: (value: T, index: number, source: Observable) => boolean): MonoTypeOperatorFunction { return operate((source, subscriber) => { From 33b7c009b3590f70d07e789b029027cd8538445d Mon Sep 17 00:00:00 2001 From: Nicholas Jamieson Date: Wed, 17 Mar 2021 17:02:48 +1000 Subject: [PATCH 3/3] docs: remove mention of selector from share --- src/internal/operators/share.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/internal/operators/share.ts b/src/internal/operators/share.ts index d89d23ec6c..e12fbc8692 100644 --- a/src/internal/operators/share.ts +++ b/src/internal/operators/share.ts @@ -88,8 +88,7 @@ export function share(options: ShareConfig): MonoTypeOperatorFunction; * @see {@link api/index/function/interval} * @see {@link map} * - * @return A function that returns an Observable that upon connection causes - * the source Observable to emit items to its Observers. + * @return A function that returns an Observable that mirrors the source. */ export function share(options?: ShareConfig): OperatorFunction { options = options || {};