Merge branch 'mpodlasin-pairs-docs'

src/internal/observable/pairs.ts

@@ -4,32 +4,49 @@ import { Subscriber } from '../Subscriber';
 import { Subscription } from '../Subscription';
 
 /**
- * Convert an object into an observable sequence of [key, value] pairs
- * using an optional {@link SchedulerLike} to enumerate the object.
+ * Convert an object into an Observable of `[key, value]` pairs.
  *
- * ## Example
- * Converts a javascript object to an Observable
+ * <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 SchedulerLike} as a second argument to `pairs`.
+ *
+ * @example <caption>Converts a javascript object to an Observable</caption>
  * ```javascript
  * const obj = {
  *   foo: 42,
  *   bar: 56,
- *   baz: 78,
+ *   baz: 78
  * };
  *
- * const source = pairs(obj);
- *
- * const subscription = source.subscribe(
- *   x => console.log('Next: %s', x),
- *   err => console.log('Error: %s', err),
- *   () => console.log('Completed'),
+ * 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 {SchedulerLike} [scheduler] An optional {@link SchedulerLike} to run the
- * enumeration of the input sequence on.
- * @returns {(Observable<[string, T]>)} An observable sequence of
+ * @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.
  */
 export function pairs<T>(obj: Object, scheduler?: SchedulerLike): Observable<[string, T]> {