docs(Observable): add documentation for Observable and operators

Closes #5642
Closes #5684

modules/angular2/examples/facade/ts/async/observable.ts

@@ -0,0 +1,8 @@
+// #docregion Observable
+import {Observable} from 'angular2/core';
+var obs = new Observable<number>(obs => {
+  var i = 0;
+  setInterval(_ => { obs.next(++i); }, 1000);
+});
+obs.subscribe(i => console.log(`${i} seconds elapsed`));
+// #enddocregion

modules/angular2/examples/facade/ts/async/observable_all.ts

@@ -0,0 +1,3 @@
+// #docregion Observable
+import 'rxjs';
+// #enddocregion

modules/angular2/examples/facade/ts/async/observable_patched.ts

@@ -0,0 +1,10 @@
+// #docregion Observable
+import {Observable} from 'angular2/core';
+import 'rxjs/add/operator/map';
+
+var obs = new Observable(obs => {
+  var i = 0;
+  setInterval(_ => obs.next(++i), 1000);
+});
+obs.map(i => `${i} seconds elapsed`).subscribe(msg => console.log(msg));
+// #enddocregion

modules/angular2/examples/facade/ts/async/observable_pure.ts

@@ -0,0 +1,10 @@
+// #docregion Observable
+import {Observable} from 'angular2/core';
+import {map} from 'rxjs/operator/map';
+
+var obs = new Observable(obs => {
+  var i = 0;
+  setInterval(_ => obs.next(++i), 1000);
+});
+map.call(obs, i => `${i} seconds elapsed`).subscribe(msg => console.log(msg));
+// #enddocregion

modules/angular2/src/facade/async.ts

@@ -162,6 +162,66 @@ export class EventEmitter<T> extends Subject<T> {
   }
 }
 
+/**
+ * Allows publishing and subscribing to series of async values.
+ *
+ * The `Observable` class is an alias to the `Observable` returned from
+ * {@link https://github.com/reactivex/rxjs}. `Observables` are a means of delivering
+ * any number of values over any period of time. `Observables` can be thought of as a
+ * mixture of `Promise` and `Array`. `Observables` are like `Arrays` in that they can have
+ * chained combinators -- like `map`, `reduce`, and `filter` -- attached in order to
+ * perform projections and transformations of data. And they are like `Promises`
+ * in that they can asynchronously deliver values. But unlike a `Promise`, an
+ * `Observable` can emit many values over time, and decides if/when it is completed.
+ *
+ * `Observable` is also being considered for inclusion in the
+ * [ECMAScript spec](https://github.com/zenparsing/es-observable).
+ *
+ * ## Example
+ *
+ * A simple example of using an `Observable` is a timer `Observable`, which will
+ * notify an `Observer` each time an interval has completed.
+ *
+ * {@example facade/ts/async/observable.ts region='Observable'}
+ *
+ * The `Observable` in Angular currently doesn't provide any combinators by default.
+ * So it's necessary to explicitly import any combinators that an application requires.
+ * There are two ways to import RxJS combinators: pure and patched. The "pure" approach
+ * involves importing a combinator as a function every place that an application needs it,
+ * then calling the function with the source observable as the context of the function.
+ *
+ * ## Example
+ *
+ * {@example facade/ts/async/observable_pure.ts region='Observable'}
+ *
+ * The "patched" approach to using combinators is to import a special module for
+ * each combinator, which will automatically cause the combinator to be patched
+ * to the `Observable` prototype, which will make it available to use anywhere in
+ * an application after the combinator has been imported once.
+ *
+ * ## Example
+ *
+ * (Notice the extra "add" in the path to import `map`)
+ *
+ * {@example facade/ts/async/observable_patched.ts region='Observable'}
+ *
+ * Notice that the sequence of operations is now able to be expressed "left-to-right"
+ * because `map` is on the `Observable` prototype. For a simple example like this one,
+ * the left-to-right expression may seem insignificant. However, when several operators
+ * are used in combination, the "callback tree" grows several levels deep, and becomes
+ * difficult to read. For this reason, the "patched" approach is the recommended approach
+ * to add new operators to `Observable`.
+ *
+ * For applications that are less sensitive about payload size, the set of core operators
+ * can be patched onto the `Observable` prototype with a single import, by importing the
+ * `rxjs` module.
+ *
+ * {@example facade/ts/async/observable_all.ts region='Observable'}
+ *
+ * Full documentation on RxJS `Observable` and available combinators can be found
+ * in the RxJS [Observable docs](http://reactivex.io/RxJS/class/es6/Observable.js~Observable.html).
+ *
+ */
 // todo(robwormald): ts2dart should handle this properly
 export class Observable<T> extends RxObservable<T> {
   lift<T, R>(operator: Operator<T, R>): Observable<T> {