docs(operators): write comprehensive JSDoc on auditTime()

src/operator/auditTime.ts

@@ -6,26 +6,62 @@ import {Observable} from '../Observable';
 import {Subscription} from '../Subscription';
 
 /**
- * @param delay
- * @param scheduler
- * @return {Observable<R>|WebSocketSubject<T>|Observable<T>}
+ * Ignores source values for `duration` milliseconds, then emits the most recent
+ * value from the source Observable, then repeats this process.
+ *
+ * <span class="informal">When it sees a source values, it ignores that plus
+ * the next ones for `duration` milliseconds, and then it emits the most recent
+ * value from the source.</span>
+ *
+ * <img src="./img/auditTime.png" width="100%">
+ *
+ * `auditTime` is similar to `throttleTime`, but emits the last value from the
+ * silenced time window, instead of the first value. `auditTime` emits the most
+ * recent value from the source Observable on the output Observable as soon as
+ * its internal timer becomes disabled, and ignores source values while the
+ * timer is enabled. Initially, the timer is disabled. As soon as the first
+ * source value arrives, the timer is enabled. After `duration` milliseconds (or
+ * the time unit determined internally by the optional `scheduler`) has passed,
+ * the timer is disabled, then the most recent source value is emitted on the
+ * output Observable, and this process repeats for the next source value.
+ * Optionally takes a {@link Scheduler} for managing timers.
+ *
+ * @example <caption>Emit clicks at a rate of at most one click per second</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var result = clicks.auditTime(1000);
+ * result.subscribe(x => console.log(x));
+ *
+ * @see {@link audit}
+ * @see {@link debounceTime}
+ * @see {@link delay}
+ * @see {@link sampleTime}
+ * @see {@link throttleTime}
+ *
+ * @param {number} duration Time to wait before emitting the most recent source
+ * value, measured in milliseconds or the time unit determined internally
+ * by the optional `scheduler`.
+ * @param {Scheduler} [scheduler=async] The {@link Scheduler} to use for
+ * managing the timers that handle the rate-limiting behavior.
+ * @return {Observable<T>} An Observable that performs rate-limiting of
+ * emissions from the source Observable.
  * @method auditTime
  * @owner Observable
  */
-export function auditTime<T>(delay: number, scheduler: Scheduler = async): Observable<T> {
- return this.lift(new AuditTimeOperator(delay, scheduler));
+export function auditTime<T>(duration: number, scheduler: Scheduler = async): Observable<T> {
+ return this.lift(new AuditTimeOperator(duration, scheduler));
 }
 
 export interface AuditTimeSignature<T> {
- (delay: number, scheduler?: Scheduler): Observable<T>;
+ (duration: number, scheduler?: Scheduler): Observable<T>;
 }
 
 class AuditTimeOperator<T> implements Operator<T, T> {
- constructor(private delay: number, private scheduler: Scheduler) {
+ constructor(private duration: number,
+ private scheduler: Scheduler) {
  }
 
  call(subscriber: Subscriber<T>, source: any): any {
- return source._subscribe(new AuditTimeSubscriber(subscriber, this.delay, this.scheduler));
+ return source._subscribe(new AuditTimeSubscriber(subscriber, this.duration, this.scheduler));
  }
 }
 
@@ -41,7 +77,7 @@ class AuditTimeSubscriber<T> extends Subscriber<T> {
  private throttled: Subscription;
 
  constructor(destination: Subscriber<T>,
- private delay: number,
+ private duration: number,
  private scheduler: Scheduler) {
  super(destination);
  }
@@ -50,7 +86,7 @@ class AuditTimeSubscriber<T> extends Subscriber<T> {
  this.value = value;
  this.hasValue = true;
  if (!this.throttled) {
- this.add(this.throttled = this.scheduler.schedule(dispatchNext, this.delay, this));
+ this.add(this.throttled = this.scheduler.schedule(dispatchNext, this.duration, this));
  }
  }