From a435e86e757d5a079502f10186013b645c694975 Mon Sep 17 00:00:00 2001
From: Mateusz Podlasin <Podlas29@gmail.com>
Date: Wed, 29 Mar 2017 18:54:27 +0200
Subject: [PATCH] docs(pairs): document the operator

Describe what it accepts and returns. Note
what kind of object properties will be emitted.
Add note about optional scheduler parameter.
---
 spec/observables/pairs-spec.ts    | 13 +++--
 src/observable/PairsObservable.ts | 81 +++++++++++++++++++------------
 2 files changed, 57 insertions(+), 37 deletions(-)

diff --git a/spec/observables/pairs-spec.ts b/spec/observables/pairs-spec.ts
index d5cf8b0615..09974ccf9c 100644
--- a/spec/observables/pairs-spec.ts
+++ b/spec/observables/pairs-spec.ts
@@ -8,12 +8,15 @@ declare const rxTestScheduler: Rx.TestScheduler;
 const Observable = Rx.Observable;
 
 describe('Observable.pairs', () => {
-  asDiagram('pairs({a: 1, b:2})')('should create an observable emits key-value pair', () => {
-    const e1 = Observable.pairs({a: 1, b: 2}, rxTestScheduler);
-    const expected = '(ab|)';
+  asDiagram('pairs({a: 1, b: 2, c: 3})')('should create an observable emits key-value pair', () => {
+    const e1 = Observable.pairs({a: 1, b: 2, c: 3}, rxTestScheduler)
+    // for the purpose of making a nice diagram, spread out the synchronous emissions
+    .concatMap((x, i) => Observable.of(x).delay(i === 0 ? 0 : 20, rxTestScheduler));
+    const expected = 'a-b-(c|)';
     const values = {
       a: ['a', 1],
-      b: ['b', 2]
+      b: ['b', 2],
+      c: ['c', 3]
     };
 
     expectObservable(e1).toBe(expected, values);
@@ -42,4 +45,4 @@ describe('Observable.pairs', () => {
 
     expectObservable(e1).toBe(expected);
   });
-});
\ No newline at end of file
+});
diff --git a/src/observable/PairsObservable.ts b/src/observable/PairsObservable.ts
index 57656f5ad8..59066f132f 100644
--- a/src/observable/PairsObservable.ts
+++ b/src/observable/PairsObservable.ts
@@ -36,37 +36,54 @@ function dispatch<T>(this: Action<PairsContext<T>>, state: PairsContext<T>) {
 export class PairsObservable<T> extends Observable<Array<string | T>> {
   private keys: Array<string>;
 
-  /**
-   * Convert an object into an observable sequence of [key, value] pairs
-   * using an optional IScheduler to enumerate the object.
-   *
-   * @example <caption>Converts a javascript object to an Observable</caption>
-   * var obj = {
-   *   foo: 42,
-   *   bar: 56,
-   *   baz: 78
-   * };
-   *
-   * var source = Rx.Observable.pairs(obj);
-   *
-   * var subscription = source.subscribe(
-   *   function (x) {
-   *     console.log('Next: %s', x);
-   *   },
-   *   function (err) {
-   *     console.log('Error: %s', err);
-   *   },
-   *   function () {
-   *     console.log('Completed');
-   *   });
-   *
-   * @param {Object} obj The object to inspect and turn into an
-   * Observable sequence.
-   * @param {Scheduler} [scheduler] An optional IScheduler to run the
-   * enumeration of the input sequence on.
-   * @returns {(Observable<Array<string | T>>)} An observable sequence of
-   * [key, value] pairs from the object.
-   */
+/**
+ * Convert an object into an Observable of `[key, value]` pairs.
+ *
+ * <span class="informal">Turn entries of an object into a stream.</span>
+ *
+ * <img src="./img/pairs.png" width="100%">
+ *
+ * `pairs` takes an arbitrary object and returns an Observable that emits arrays. Each
+ * emitted array has exactly two elements - the first is a key from the object
+ * and the second is a value corresponding to that key. Keys are extracted from
+ * an object via `Object.keys` function, which means that they will be only
+ * enumerable keys that are present on an object directly - not ones inherited
+ * via prototype chain.
+ *
+ * By default these arrays are emitted synchronously. To change that you can
+ * pass a {@link Scheduler} as a second argument to `pairs`.
+ *
+ * @example <caption>Converts a javascript object to an Observable</caption>
+ * var obj = {
+ *   foo: 42,
+ *   bar: 56,
+ *   baz: 78
+ * };
+ *
+ * Rx.Observable.pairs(obj)
+ * .subscribe(
+ *   value => console.log(value),
+ *   err => {},
+ *   () => console.log('the end!')
+ * );
+ *
+ * // Logs:
+ * // ["foo": 42],
+ * // ["bar": 56],
+ * // ["baz": 78],
+ * // "the end!"
+ *
+ *
+ * @param {Object} obj The object to inspect and turn into an
+ * Observable sequence.
+ * @param {Scheduler} [scheduler] An optional IScheduler to schedule
+ * when resulting Observable will emit values.
+ * @returns {(Observable<Array<string|T>>)} An observable sequence of
+ * [key, value] pairs from the object.
+ * @static true
+ * @name pairs
+ * @owner Observable
+ */
   static create<T>(obj: Object, scheduler?: IScheduler): Observable<Array<string | T>> {
     return new PairsObservable<T>(obj, scheduler);
   }
@@ -92,4 +109,4 @@ export class PairsObservable<T> extends Observable<Array<string | T>> {
       subscriber.complete();
     }
   }
-}
\ No newline at end of file
+}