docs(server-communication): cleanup, mainly for Dart (#1455)

- Dart code: fix issues raised by @thso during review.
- Dart code: remove "show x" clauses from imports.
- Dart add docsync config file.
- Prose: make consistent use of _Http variables; otherwise use "HTTP".
- Prose: add links to the demos list.

* _heroesUrl as static const

public/docs/_examples/server-communication/dart/.docsync.json

@@ -0,0 +1,4 @@
+{
+  "name": "HTTP client (server communication)"
+  "docHref": "https://angular.io/docs/dart/latest/guide/server-communication.html"
+}

public/docs/_examples/server-communication/dart/lib/app_component.dart

@@ -1,13 +1,13 @@
 // #docplaster
 // #docregion
-import "package:angular2/core.dart" show Component;
+import 'package:angular2/core.dart';
 
-import "toh/hero_list_component.dart" show HeroListComponent;
+import 'toh/hero_list_component.dart';
-import "wiki/wiki_component.dart" show WikiComponent;
+import 'wiki/wiki_component.dart';
-import "wiki/wiki_smart_component.dart" show WikiSmartComponent;
+import 'wiki/wiki_smart_component.dart';
 
 @Component(
-    selector: "my-app",
+    selector: 'my-app',
     template: '''
       <hero-list></hero-list>
       <my-wiki></my-wiki>

public/docs/_examples/server-communication/dart/lib/toh/hero.dart

@@ -1,4 +1,6 @@
 // #docregion
+int _toInt(id) => id is int ? id : int.parse(id);
+
 class Hero {
   final int id;
   final String name;
@@ -9,6 +11,4 @@ class Hero {
       new Hero(_toInt(hero['id']), hero['name']);
 
   Map toJson() => {'id': id, 'name': name};
-
-  static int _toInt(id) => id is int ? id : int.parse(id);
 }

public/docs/_examples/server-communication/dart/lib/toh/hero_service.dart

@@ -6,12 +6,12 @@ import 'dart:convert';
 import 'hero.dart';
 import 'package:angular2/core.dart';
 import 'package:http/browser_client.dart';
-import 'package:http/http.dart' show Response;
+import 'package:http/http.dart';
 
 @Injectable()
 class HeroService {
   // #docregion endpoint, http-get
-  final String _heroesUrl = 'app/heroes';  // URL to web API
+  static const _heroesUrl = 'app/heroes'; // URL to web API
   // #enddocregion endpoint, http-get
   final BrowserClient _http;
 
@@ -35,7 +35,7 @@ class HeroService {
 
   // #docregion addhero, addhero-sig
   Future<Hero> addHero(String name) async {
-  // #enddocregion addhero-sig
+    // #enddocregion addhero-sig
     try {
       final response = await _http.post(_heroesUrl,
           headers: {'Content-Type': 'application/json'},
@@ -50,8 +50,8 @@ class HeroService {
   // #docregion extract-data
   dynamic _extractData(Response res) {
     var body = JSON.decode(res.body);
-    // TODO: once fixed, https://github.com/adaojunior/http-in-memory-web-api/issues/1
+    // TODO: https://github.com/adaojunior/http-in-memory-web-api/issues/1
-    // Drop the `?? body` term
+    // Once #1 is fixed, drop the `?? body` term:
     return body['data'] ?? body;
   }
   // #enddocregion extract-data
@@ -69,6 +69,6 @@ class HeroService {
 
 /*
   // #docregion endpoint-json
-  private _heroesUrl = 'heroes.json'; // URL to JSON file
+  static const _heroesUrl = 'heroes.json'; // URL to JSON file
   // #enddocregion endpoint-json
 */

public/docs/_examples/server-communication/dart/pubspec.yaml

@@ -23,4 +23,3 @@ transformers:
     resolved_identifiers:
         BrowserClient: 'package:http/browser_client.dart'
 - dart_to_js_script_rewriter
-# #enddocregion transformers

public/docs/_examples/server-communication/dart/web/main.dart

@@ -1,10 +1,10 @@
 // #docplaster
 // #docregion final
-import 'package:angular2/core.dart' show Provider;
+import 'package:angular2/core.dart';
 // #docregion v1
-import 'package:angular2/platform/browser.dart' show bootstrap;
+import 'package:angular2/platform/browser.dart';
 // #docregion http-providers
-import 'package:http/browser_client.dart' show BrowserClient;
+import 'package:http/browser_client.dart';
 // #enddocregion http-providers
 
 import 'package:server_communication/app_component.dart';

public/docs/dart/latest/guide/_data.json

@@ -80,8 +80,8 @@
   },
 
   "server-communication": {
-    "title": "Http Client",
+    "title": "HTTP Client",
-    "intro": "Talk to a remote server with the Angular Http Client."
+    "intro": "Talk to a remote server with an HTTP Client."
   },
 
   "lifecycle-hooks": {

public/docs/dart/latest/guide/server-communication.jade

@@ -5,11 +5,11 @@ block includes
   - var _Http = 'BrowserClient';
   - var _Angular_Http = 'Dart <code>BrowserClient</code>'
   - var _httpUrl = 'https://pub.dartlang.org/packages/http'
-  - var _Angular_http_library = 'Dart <a href="!{_httpUrl}"><b>http</b> library</a>'
+  - var _Angular_http_library = 'Dart <a href="' + _httpUrl + '"><b>http</b></a> library'
 
 block demos-list
-  li HTTP client: Tour of Heroes
+  li #[a(href="#http-client") HTTP client: Tour of Heroes]
-  li JSONP client: Wikipedia to fetch data from a service that doesn't support CORS (under development)
+  li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] #[b (under development)]
 
 block rxjs-import
   //- N/A

public/docs/js/latest/guide/_data.json

@@ -80,8 +80,8 @@
   },
 
   "server-communication": {
-    "title": "Http Client",
+    "title": "HTTP Client",
-    "intro": "Talk to a remote server with the Angular Http Client."
+    "intro": "Talk to a remote server with an HTTP Client."
   },
 
   "lifecycle-hooks": {

public/docs/ts/latest/guide/_data.json

@@ -80,8 +80,8 @@
   },
 
   "server-communication": {
-    "title": "Http Client",
+    "title": "HTTP Client",
-    "intro": "Talk to a remote server with the Angular Http Client."
+    "intro": "Talk to a remote server with an HTTP Client."
   },
 
   "lifecycle-hooks": {

public/docs/ts/latest/guide/server-communication.jade

@@ -16,7 +16,7 @@ block includes
   [JSONP](https://en.wikipedia.org/wiki/JSONP). A few browsers also support
   [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). 
   
-  The Angular HTTP client library simplifies application programming of the **XHR** and **JSONP** APIs
+  The !{_Angular_http_library} simplifies application programming of the **XHR** and **JSONP** APIs
   as we'll learn in this chapter covering:
 
 ul
@@ -30,7 +30,7 @@ ul
   li #[a(href="#update") Send data to the server]
   +ifDocsFor('ts')
     li #[a(href="#promises") Promises instead of observables]
-  li #[a(href="#cross-origin-requests") Cross-origin requests: Wikipedia example]
+  li #[a(href="#cors") Cross-origin requests: Wikipedia example]
   +ifDocsFor('ts')
     ul
       li #[a(href="#search-parameters") Set query string parameters]
@@ -45,10 +45,10 @@ h1 Demos
 p  This chapter describes server communication with the help of the following demos
 ul
   block demos-list
-    li HTTP client: Tour of Heroes with Observables
+    li #[a(href="#http-client") HTTP client: Tour of Heroes with Observables]
-    li HTTP client: Tour of Heroes with #{_Promise}s
+    li #[a(href="#promises") HTTP client: Tour of Heroes with #{_Promise}s]
-    li JSONP client: Wikipedia to fetch data from a service that doesn't support CORS
+    li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS]
-    li JSONP client: Wikipedia using observable operators to reduce server calls
+    li #[a(href="#more-observables") JSONP client: Wikipedia using observable operators to reduce server calls]
 :marked
   These demos are orchestrated by the root `AppComponent`
 +makeExample('server-communication/ts/app/app.component.ts', null, 'app/app.component.ts')
@@ -58,7 +58,7 @@ block rxjs-import
     There is nothing remarkable here _except_ for the import of RxJS operators.
   +makeExample('server-communication/ts/app/app.component.ts', 'import-rxjs')(format='.')
   :marked
-    We'll talk about that [below](#rxjs) when we're ready to explore observables. 
+    We'll talk about that [below](#rxjs) when we're ready to explore observables.
 :marked
   First, we have to configure our application to use server communication facilities.
 
@@ -66,14 +66,14 @@ block rxjs-import
 h1#http-providers Providing HTTP Services
 :marked
   We use the !{_Angular_Http} client to communicate with a server using a familiar HTTP request/response protocol.
-  The `!{_Http}` client is one of a family of services in the !{_Angular_http_library}.
+  The `#{_Http}` client is one of a family of services in the !{_Angular_http_library}.
 block system-config-of-http
   .l-sub-section
     :marked
       SystemJS knows how to load services from the !{_Angular_http_library} when we import from the `@angular/http` module
       because we registered that module name in the `system.config` file.
 :marked
-    Before we can use the `!{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system.
+    Before we can use the `#{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system.
 .l-sub-section
   :marked
     Learn about providers in the [Dependency Injection](dependency-injection.html) chapter.
@@ -84,7 +84,7 @@ p In this demo, we register providers in the #[code bootstrap] method of #[code
 block http-providers
   :marked
     We begin by importing the symbols we need, most of them familiar by now. The newcomer is `HTTP_PROVIDERS`, 
-    a collection of service providers from the Angular HTTP library.
+    a collection of service providers from the !{_Angular_http_library}.
  
     We register HTTP providers in the bootstrap method by passing them in an array as the second parameter after the root component.
 
@@ -105,10 +105,8 @@ block http-providers
     For this reason, and this reason *only*, we hide it *above* the `AppComponent` in `main.ts`.
 
 .l-main-section
-a#http-client
+h1#http-client The Tour of Heroes #[i HTTP] Client Demo
 :marked
-  # The Tour of Heroes *HTTP* Client Demo
-  
   Our first demo is a mini-version of the [tutorial](../tutorial)'s "Tour of Heroes" (ToH) application.
   This version gets some heroes from the server, displays them in a list, lets us add new heroes, and saves them to the server.
   We use the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`.
@@ -182,7 +180,7 @@ h2#fetch-data Fetch data with the #[b HeroService]
 +makeExample('server-communication/ts/app/toh/hero.service.ts', 'v1', 'app/toh/hero.service.ts (revised)')
 
 :marked
-  Notice that the Angular `!{_Http}` client service is
+  Notice that the !{_Angular_Http} client service is
   [injected](dependency-injection.html) into the `HeroService` constructor.
 +makeExample('server-communication/ts/app/toh/hero.service.ts', 'ctor')
 :marked
@@ -412,10 +410,8 @@ block hero-list-comp-add-hero
 +makeExample('server-communication/ts/app/toh/hero-list.component.ts', 'addHero', 'app/toh/hero-list.component.ts (addHero)')(format=".")
 
 block promises
-  a#promises
+  h2#promises Fall back to Promises
   :marked
-    ## Fall back to Promises
-
     Although the Angular `http` client API returns an `Observable<Response>` we can turn it into a 
     [Promise<Response>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) if we prefer.
     It's easy to do and a promise-based version looks much like the observable-based version in simple cases.
@@ -461,11 +457,9 @@ block promises
 
       Learn more about observables to understand the implications and consequences of subscriptions.
 
-a#cross-origin-requests
+h2#cors Cross-origin requests: Wikipedia example
 :marked
-  ## Cross-origin requests: Wikipedia example
+  We just learned how to make `XMLHttpRequests` using the !{_Angular_Http} service. 
-
-  We just learned how to make `XMLHttpRequests` using Angular's built-in `Http` service. 
   This is the most common approach for server communication. 
   It doesn't work in all scenarios.
 
@@ -496,7 +490,7 @@ figure.image-display
 block wikipedia-jsonp+
   :marked
     Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API. Let's use the latter for this example.
-    The Angular `Jsonp` service both extends the `Http` service for JSONP and restricts us to `GET` requests. 
+    The Angular `Jsonp` service both extends the `#{_Http}` service for JSONP and restricts us to `GET` requests. 
     All other HTTP methods throw an error because JSONP is a read-only facility. 
 
     As always, we wrap our interaction with an Angular data access client service inside a dedicated service, here called `WikipediaService`.