docs(http): add docs and examples for JSONP_BINDINGS

Author: jeffbcross

modules/angular2/http.ts

@@ -162,6 +162,112 @@ export const HTTP_BINDINGS: any[] = [
   XHRBackend
 ];
 
+
+/**
+ * Provides a basic set of bindings to use the {@link Jsonp} service in any application.
+ *
+ * The `JSONP_BINDINGS` should be included either in a component's injector,
+ * or in the root injector when bootstrapping an application.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/vmeN4F?p=preview))
+ *
+ * ```
+ * import {Component, NgFor, View} from 'angular2/angular2';
+ * import {JSONP_BINDINGS, Jsonp} from 'angular2/http';
+ *
+ * @Component({
+ *   selector: 'app',
+ *   bindings: [JSONP_BINDINGS]
+ * })
+ * @View({
+ *   template: `
+ *     <div>
+ *       <h1>People</h1>
+ *       <ul>
+ *         <li *ng-for="#person of people">
+ *           {{person.name}}
+ *         </li>
+ *       </ul>
+ *     </div>
+ *   `,
+ *   directives: [NgFor]
+ * })
+ * export class App {
+ *   people: Array<Object>;
+ *   constructor(jsonp:Jsonp) {
+ *     jsonp.request('people.json').toRx().subscribe(res => {
+ *       this.people = res.json();
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * The primary public API included in `JSONP_BINDINGS` is the {@link Jsonp} class.
+ * However, other bindings required by `Jsonp` are included,
+ * which may be beneficial to override in certain cases.
+ *
+ * The bindings included in `JSONP_BINDINGS` include:
+ *  * {@link Jsonp}
+ *  * {@link JSONPBackend}
+ *  * `BrowserJsonp` - Private factory
+ *  * {@link RequestOptions} - Bound to {@link BaseRequestOptions} class
+ *  * {@link ResponseOptions} - Bound to {@link BaseResponseOptions} class
+ *
+ * There may be cases where it makes sense to extend the base request options,
+ * such as to add a search string to be appended to all URLs.
+ * To accomplish this, a new binding for {@link RequestOptions} should
+ * be added in the same injector as `JSONP_BINDINGS`.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/TFug7x?p=preview))
+ *
+ * ```
+ * import {bind, bootstrap} from 'angular2/angular2';
+ * import {JSONP_BINDINGS, BaseRequestOptions, RequestOptions} from 'angular2/http';
+ *
+ * class MyOptions extends BaseRequestOptions {
+ *   search: string = 'coreTeam=true';
+ * }
+ *
+ * bootstrap(App, [JSONP_BINDINGS, bind(RequestOptions).toClass(MyOptions)])
+ *   .catch(err => console.error(err));
+ * ```
+ *
+ * Likewise, to use a mock backend for unit tests, the {@link JSONPBackend}
+ * binding should be bound to {@link MockBackend}.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/HDqZWL?p=preview))
+ *
+ * ```
+ * import {bind, Injector} from 'angular2/angular2';
+ * import {JSONP_BINDINGS, Jsonp, Response, JSONPBackend, MockBackend} from 'angular2/http';
+ *
+ * var people = [{name: 'Jeff'}, {name: 'Tobias'}];
+ * var injector = Injector.resolveAndCreate([
+ *   JSONP_BINDINGS,
+ *   MockBackend,
+ *   bind(JSONPBackend).toAlias(MockBackend)
+ * ]);
+ * var jsonp = injector.get(Jsonp);
+ * var backend = injector.get(MockBackend);
+ *
+ * // Listen for any new requests
+ * backend.connections.observer({
+ *   next: connection => {
+ *     var response = new Response({body: people});
+ *     setTimeout(() => {
+ *       // Send a response to the request
+ *       connection.mockRespond(response);
+ *     });
+ *   });
+
+ * jsonp.get('people.json').observer({
+ *   next: res => {
+ *     // Response came from mock backend
+ *     console.log('first person', res.json()[0].name);
+ *   }
+ * });
+ * ```
+ */
 export const JSONP_BINDINGS: any[] = [
   // TODO(pascal): use factory type annotations once supported in DI
   // issue: https://github.com/angular/angular/issues/3183