docs(Http): add docs about breaking changes with EventEmitter/Observable

BREAKING CHANGE:
    The Http module previously would return RxJS Observables from method calls
    of the Http class. In order to support Dart, the module was refactored to
    return the EventEmitter abstraction instead, which does not contain the same
    combinators or subscription semantics as an RxJS Observable. However, the
    EventEmitter provides a toRx() method which will return an RxJS Subject,
    providing the same subscription and combinator conveniences as were
    available prior to this refactor.

    This is temporary, until issue angular#2794 is resolved, when Observables will
    again be returned directly from Http class methods.

Author: jeffbcross

modules/angular2/src/http/http.ts

@@ -36,8 +36,17 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
  *
  * `Http` is available as an injectable class, with methods to perform http requests. Calling
  * `request` returns an {@link EventEmitter} which will emit a single {@link Response} when a
- *response is
- * received.
+ * response is received.
+ *
+ *
+ * ## Breaking Change
+ *
+ * Previously, methods of `Http` would return an RxJS Observable directly. For now,
+ * the `toRx()` method of {@link EventEmitter} needs to be called in order to get the RxJS
+ * Subject. `EventEmitter` does not provide combinators like `map`, and has different semantics for
+ * subscribing/observing. This is temporary; the result of all `Http` method calls will be either an
+ * Observable
+ * or Dart Stream when [issue #2794](https://github.com/angular/angular/issues/2794) is resolved.
  *
  * #Example
  *
@@ -47,7 +56,9 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
  * @View({templateUrl: 'people.html'})
  * class PeopleComponent {
  *   constructor(http: Http) {
- *     http('people.json')
+ *     http.get('people.json')
+ *       //Get the RxJS Subject
+ *       .toRx()
  *       // Call map on the response observable to get the parsed people object
  *       .map(res => res.json())
  *       // Subscribe to the observable to get the parsed people object and attach it to the
@@ -57,6 +68,16 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
  * }
  * ```
  *
+ * To use the {@link EventEmitter} returned by `Http`, simply pass a generator (See "interface
+ *Generator" in the Async Generator spec: https://github.com/jhusain/asyncgenerator) to the
+ *`observer` method of the returned emitter, with optional methods of `next`, `throw`, and `return`.
+ *
+ * #Example
+ *
+ * ```
+ * http.get('people.json').observer({next: (value) => this.people = people});
+ * ```
+ *
  * The default construct used to perform requests, `XMLHttpRequest`, is abstracted as a "Backend" (
  * {@link XHRBackend} in this case), which could be mocked with dependency injection by replacing
  * the {@link XHRBackend} binding, as in the following example:
@@ -75,7 +96,7 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
  *       [MockBackend, BaseRequestOptions])
  * ]);
  * var http = injector.get(Http);
- * http.get('request-from-mock-backend.json').subscribe((res:Response) => doSomething(res));
+ * http.get('request-from-mock-backend.json').toRx().subscribe((res:Response) => doSomething(res));
  * ```
  *
  **/