docs(operators): fix @return docs (#5447)

* docs(operators): fix @return docs

* docs: single will not emit undefined

* docs: remove mention of selector from share

Co-authored-by: Nicholas Jamieson <nicholas@cartant.com>

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<T>(durationSelector: (value: T) => ObservableInput<any>): MonoTypeOperatorFunction<T> {

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<T>} 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<T>(duration: number, scheduler: SchedulerLike = async): MonoTypeOperatorFunction<T> {

src/internal/operators/buffer.ts

@@ -39,8 +39,8 @@ import { OperatorSubscriber } from './OperatorSubscriber';
  *
  * @param {Observable<any>} closingNotifier An Observable that signals the
  * buffer to be emitted on the output Observable.
- * @return {Observable<T[]>} 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<T>(closingNotifier: Observable<any>): OperatorFunction<T, T[]> {
   return operate((source, subscriber) => {

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<T[]>} An Observable of arrays of buffered values.
+ * @return A function that returns an Observable of arrays of buffered values.
  */
 export function bufferCount<T>(bufferSize: number, startBufferEvery: number | null = null): OperatorFunction<T, T[]> {
   // If no `startBufferEvery` value was supplied, then we're

src/internal/operators/bufferTime.ts

@@ -74,7 +74,7 @@ export function bufferTime<T>(
  * @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<T[]>} An observable of arrays of buffered values.
+ * @return A function that returns an Observable of arrays of buffered values.
  */
 export function bufferTime<T>(bufferTimeSpan: number, ...otherArgs: any[]): OperatorFunction<T, T[]> {
   const scheduler = popScheduler(otherArgs) ?? asyncScheduler;

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<T, O>(
   openings: ObservableInput<O>,

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<T[]>} An observable of arrays of buffered values.
+ * @return A function that returns an Observable of arrays of buffered values.
  */
 export function bufferWhen<T>(closingSelector: () => ObservableInput<any>): OperatorFunction<T, T[]> {
   return operate((source, subscriber) => {

src/internal/operators/catchError.ts

@@ -97,11 +97,11 @@ export function catchError<T, O extends ObservableInput<any>>(
  * @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<T, O extends ObservableInput<any>>(
   selector: (err: any, caught: Observable<T>) => O

src/internal/operators/combineLatestAll.ts

@@ -6,6 +6,7 @@ export function combineLatestAll<T>(): OperatorFunction<ObservableInput<T>, T[]>
 export function combineLatestAll<T>(): OperatorFunction<any, T[]>;
 export function combineLatestAll<T, R>(project: (...values: T[]) => R): OperatorFunction<ObservableInput<T>, R>;
 export function combineLatestAll<R>(project: (...values: Array<any>) => R): OperatorFunction<any, R>;
+
 /**
  * Flattens an Observable-of-Observables by applying {@link combineLatest} when the Observable-of-Observables completes.
  *
@@ -50,6 +51,8 @@ export function combineLatestAll<R>(project: (...values: Array<any>) => 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<R>(project?: (...values: Array<any>) => R) {
   return joinAllInternals(combineLatest, project);

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<T, A extends readonly unknown[]>(
   ...otherSources: [...ObservableInputTuple<A>]

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<O extends ObservableInput<any>>(): OperatorFunction<O, ObservedValueOf<O>> {
   return mergeAll(1);

src/internal/operators/concatMap.ts

@@ -71,10 +71,10 @@ export function concatMap<T, R, O extends ObservableInput<any>>(
  * @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<T, R, O extends ObservableInput<any>>(
   project: (value: T, index: number) => O,

src/internal/operators/concatMapTo.ts

@@ -66,9 +66,9 @@ export function concatMapTo<T, R, O extends ObservableInput<unknown>>(
  *
  * @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<T, R, O extends ObservableInput<unknown>>(
   innerObservable: O,

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<T, A extends readonly unknown[]>(
   ...otherSources: [...ObservableInputTuple<A>]

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<T>(predicate?: (value: T, index: number) => boolean): OperatorFunction<T, number> {

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<T>(durationSelector: (value: T) => ObservableInput<any>): MonoTypeOperatorFunction<T> {

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<T>(dueTime: number, scheduler: SchedulerLike = asyncScheduler): MonoTypeOperatorFunction<T> {
   return operate((source, subscriber) => {

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<T, R>(defaultValue: R): OperatorFunction<T, T | R> {
   return operate((source, subscriber) => {

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<T>(due: number | Date, scheduler: SchedulerLike = asyncScheduler): MonoTypeOperatorFunction<T> {
   const duration = timer(due, scheduler);

src/internal/operators/delayWhen.ts

@@ -72,9 +72,9 @@ export function delayWhen<T>(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<T>(
   delayDurationSelector: (value: T, index: number) => Observable<any>,

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<N extends ObservableNotification<any>>(): OperatorFunction<N, ValueFromNotification<N>> {
   return operate((source, subscriber) => {

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<T, K>(keySelector?: (value: T) => K, flushes?: Observable<any>): MonoTypeOperatorFunction<T> {
   return operate((source, subscriber) => {

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<T>(comparator?: (previous: T, current: T) => boolean): MonoTypeOperatorFunction<T>;
 
@@ -134,6 +136,8 @@ export function distinctUntilChanged<T>(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<T, K>(
   comparator: (previous: K, current: K) => boolean,

src/internal/operators/distinctUntilKeyChanged.ts

@@ -72,7 +72,8 @@ export function distinctUntilKeyChanged<T, K extends keyof T>(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<T, K extends keyof T>(key: K, compare?: (x: T[K], y: T[K]) => boolean): MonoTypeOperatorFunction<T> {
   return distinctUntilChanged((x: T, y: T) => compare ? compare(x[key], y[key]) : x[key] === y[key]);

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<T, D = T>(index: number, defaultValue?: D): OperatorFunction<T, T | D> {
   if (index < 0) {

src/internal/operators/endWith.ts

@@ -55,7 +55,10 @@ export function endWith<T, A extends unknown[] = T[]>(...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}

src/internal/operators/every.ts

@@ -35,7 +35,8 @@ export function every<T>(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<T>(
   predicate: (value: T, index: number, source: Observable<T>) => boolean,

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<O extends ObservableInput<any>>(): OperatorFunction<O, ObservedValueOf<O>> {
   return operate((source, subscriber) => {

src/internal/operators/exhaustMap.ts

@@ -61,9 +61,9 @@ export function exhaustMap<T, I, R>(
  * @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<T, R, O extends ObservableInput<any>>(
   project: (value: T, index: number) => O,