From 34eaf65a79b2f43eccff8e88fb3b799d5e0906a0 Mon Sep 17 00:00:00 2001
From: Jeff Cross <middlefloor@gmail.com>
Date: Wed, 1 Jul 2015 10:15:58 -0700
Subject: [PATCH] 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 #2794 is resolved, when Observables will
    again be returned directly from Http class methods.
---
 modules/angular2/src/http/http.ts | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/modules/angular2/src/http/http.ts b/modules/angular2/src/http/http.ts
index ef00babefc..068ad25bf7 100644
--- a/modules/angular2/src/http/http.ts
+++ b/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));
  * ```
  *
  **/