docs(operators): write comprehensive JSDoc on the buffer operators

src/operator/buffer.ts

@@ -7,16 +7,33 @@ import {InnerSubscriber} from '../InnerSubscriber';
 import {subscribeToResult} from '../util/subscribeToResult';
 
 /**
- * Buffers the incoming observable values until the passed `closingNotifier`
- * emits a value, at which point it emits the buffer on the returned observable
- * and starts a new buffer internally, awaiting the next time `closingNotifier`
- * emits.
+ * Buffers the source Observable values until `closingNotifier` emits.
+ *
+ * <span class="informal">Collects values from the past as an array, and emits
+ * that array only when another Observable emits.</span>
  *
  * <img src="./img/buffer.png" width="100%">
  *
- * @param {Observable<any>} closingNotifier an Observable that signals the
- * buffer to be emitted} from the returned observable.
- * @return {Observable<T[]>} an Observable of buffers, which are arrays of
+ * Buffers the incoming Observable values until the given `closingNotifier`
+ * Observable emits a value, at which point it emits the buffer on the output
+ * Observable and starts a new buffer internally, awaiting the next time
+ * `closingNotifier` emits.
+ *
+ * @example <caption>On every click, emit array of most recent interval events</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var interval = Rx.Observable.interval(1000);
+ * var buffered = interval.buffer(clicks);
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @see {@link bufferCount}
+ * @see {@link bufferTime}
+ * @see {@link bufferToggle}
+ * @see {@link bufferWhen}
+ * @see {@link window}
+ *
+ * @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.
  * @method buffer
  * @owner Observable

src/operator/bufferCount.ts

@@ -3,20 +3,42 @@ import {Subscriber} from '../Subscriber';
 import {Observable} from '../Observable';
 
 /**
- * Buffers a number of values from the source observable by `bufferSize` then
+ * Buffers the source Observable values until the size hits the maximum
+ * `bufferSize` given.
+ *
+ * <span class="informal">Collects values from the past as an array, and emits
+ * that array only when its size reaches `bufferSize`.</span>
+ *
+ * <img src="./img/bufferCount.png" width="100%">
+ *
+ * Buffers a number of values from the source Observable by `bufferSize` then
  * emits the buffer and clears it, and starts a new buffer each
  * `startBufferEvery` values. If `startBufferEvery` is not provided or is
  * `null`, then new buffers are started immediately at the start of the source
  * and when each buffer closes and is emitted.
  *
- * <img src="./img/bufferCount.png" width="100%">
+ * @example <caption>Emit the last two click events as an array</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var buffered = clicks.bufferCount(2);
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @example <caption>On every click, emit the last two click events as an array</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var buffered = clicks.bufferCount(2, 1);
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @see {@link buffer}
+ * @see {@link bufferTime}
+ * @see {@link bufferToggle}
+ * @see {@link bufferWhen}
+ * @see {@link windowCount}
  *
- * @param {number} bufferSize the maximum size of the buffer emitted.
- * @param {number} [startBufferEvery] optional interval at which to start a new
- * buffer. (e.g. 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
+ * @param {number} bufferSize The maximum size of the buffer emitted.
+ * @param {number} [startBufferEvery] Interval at which to start a new buffer.
+ * 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 {Observable<T[]>} An Observable of arrays of buffered values.
  * @method bufferCount
  * @owner Observable
  */

src/operator/bufferTime.ts

@@ -6,19 +6,42 @@ import {Action} from '../scheduler/Action';
 import {async} from '../scheduler/async';
 
 /**
- * Buffers values from the source for a specific time period. Optionally allows
- * new buffers to be set up at an interval.
+ * Buffers the source Observable values for a specific time period.
+ *
+ * <span class="informal">Collects values from the past as an array, and emits
+ * those arrays periodically in time.</span>
  *
  * <img src="./img/bufferTime.png" width="100%">
  *
- * @param {number} bufferTimeSpan the amount of time to fill each buffer for
- * before emitting them and clearing them.
- * @param {number} [bufferCreationInterval] the interval at which to start new
+ * Buffers values from the source for a specific time duration `bufferTimeSpan`.
+ * Unless the optional argument `bufferCreationInterval` is given, it emits and
+ * resets the buffer every `bufferTimeSpan` milliseconds. If
+ * `bufferCreationInterval` is given, this operator opens the buffer every
+ * `bufferCreationInterval` milliseconds and closes (emits and resets) the
+ * buffer every `bufferTimeSpan` milliseconds.
+ *
+ * @example <caption>Every second, emit an array of the recent click events</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var buffered = clicks.bufferTime(1000);
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @example <caption>Every 5 seconds, emit the click events from the next 2 seconds</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var buffered = clicks.bufferTime(2000, 5000);
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @see {@link buffer}
+ * @see {@link bufferCount}
+ * @see {@link bufferToggle}
+ * @see {@link bufferWhen}
+ * @see {@link windowTime}
+ *
+ * @param {number} bufferTimeSpan The amount of time to fill each buffer array.
+ * @param {number} [bufferCreationInterval] The interval at which to start new
  * buffers.
- * @param {Scheduler} [scheduler] (optional, defaults to `async` scheduler) The
- * scheduler on which to schedule the intervals that determine buffer
- * boundaries.
- * @return {Observable<T[]>} an observable of arrays of buffered values.
+ * @param {Scheduler} [scheduler=async] The scheduler on which to schedule the
+ * intervals that determine buffer boundaries.
+ * @return {Observable<T[]>} An observable of arrays of buffered values.
  * @method bufferTime
  * @owner Observable
  */

src/operator/bufferToggle.ts

@@ -6,18 +6,40 @@ import {tryCatch} from '../util/tryCatch';
 import {errorObject} from '../util/errorObject';
 
 /**
+ * Buffers the source Observable values starting from an emission from
+ * `openings` and ending when the output of `closingSelector` emits.
+ *
+ * <span class="informal">Collects values from the past as an array. Starts
+ * collecting only when `opening` emits, and calls the `closingSelector`
+ * function to get an Observable that tells when to close the buffer.</span>
+ *
+ * <img src="./img/bufferToggle.png" width="100%">
+ *
  * Buffers values from the source by opening the buffer via signals from an
  * Observable provided to `openings`, and closing and sending the buffers when
- * an Observable returned by the `closingSelector` emits.
+ * an Observable returned by the `closingSelector` function emits.
  *
- * <img src="./img/bufferToggle.png" width="100%">
+ * @example <caption>Every other second, emit the click events from the next 500ms</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var openings = Rx.Observable.interval(1000);
+ * var buffered = clicks.bufferToggle(openings, i =>
+ *   i % 2 ? Rx.Observable.interval(500) : Rx.Observable.empty()
+ * );
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @see {@link buffer}
+ * @see {@link bufferCount}
+ * @see {@link bufferTime}
+ * @see {@link bufferWhen}
+ * @see {@link windowToggle}
  *
  * @param {Observable<O>} openings An observable of notifications to start new
  * buffers.
- * @param {Function} closingSelector a function that takes the value emitted by
- * the `openings` observable and returns an Observable, which, when it emits,
- * signals that the associated buffer should be emitted and cleared.
- * @return {Observable<T[]>} an observable of arrays of buffered values.
+ * @param {function(value: O): Observable} closingSelector A function that takes
+ * the value emitted by the `openings` observable and returns an Observable,
+ * which, when it emits, signals that the associated buffer should be emitted
+ * and cleared.
+ * @return {Observable<T[]>} An observable of arrays of buffered values.
  * @method bufferToggle
  * @owner Observable
  */

src/operator/bufferWhen.ts

@@ -10,15 +10,35 @@ import {InnerSubscriber} from '../InnerSubscriber';
 import {subscribeToResult} from '../util/subscribeToResult';
 
 /**
- * Opens a buffer immediately, then closes the buffer when the observable
- * returned by calling `closingSelector` emits a value. It that immediately
- * opens a new buffer and repeats the process.
+ * Buffers the source Observable values, using a factory function of closing
+ * Observables to determine when to close, emit, and reset the buffer.
+ *
+ * <span class="informal">Collects values from the past as an array. When it
+ * starts collecting values, it calls a function that returns an Observable that
+ * tells when to close the buffer and restart collecting.</span>
  *
  * <img src="./img/bufferWhen.png" width="100%">
  *
- * @param {function} 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.
+ * Opens a buffer immediately, then closes the buffer when the observable
+ * returned by calling `closingSelector` function emits a value. When it closes
+ * the buffer, it immediately opens a new buffer and repeats the process.
+ *
+ * @example <caption>Emit an array of the last clicks every [1-5] random seconds</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var buffered = clicks.bufferWhen(() =>
+ *   Rx.Observable.interval(1000 + Math.random() * 4000)
+ * );
+ * buffered.subscribe(x => console.log(x));
+ *
+ * @see {@link buffer}
+ * @see {@link bufferCount}
+ * @see {@link bufferTime}
+ * @see {@link bufferToggle}
+ * @see {@link windowWhen}
+ *
+ * @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.
  * @method bufferWhen
  * @owner Observable
  */