Merge remote-tracking branch 'origin/master'

# Conflicts:
#	public/docs/ts/latest/tutorial/toh-pt5.jade

public/docs/_examples/toh-4/dart/lib/app_component.dart

@@ -13,6 +13,7 @@ import 'hero_service.dart';
 
 @Component(
     selector: 'my-app',
+    // #docregion template
     template: '''
       <h1>{{title}}</h1>
       <h2>My Heroes</h2>
@@ -25,6 +26,7 @@ import 'hero_service.dart';
       </ul>
       <my-hero-detail [hero]="selectedHero"></my-hero-detail>
     ''',
+    // #enddocregion template
     styles: const [
     '''
       .selected {

public/docs/_examples/toh-5/dart/lib/app_component.css

@@ -1,5 +1,4 @@
-/* #docplaster */
+/* #docregion */
-/* #docregion css */
 h1 {
   font-size: 1.2em;
   color: #999;
@@ -28,4 +27,3 @@ nav a:hover {
 nav a.router-link-active {
   color: #039be5;
 }
-/* #enddocregion css */

public/docs/_examples/toh-5/dart/lib/app_component.dart

@@ -27,20 +27,19 @@ import 'package:angular2_tour_of_heroes/hero_detail_component.dart';
     directives: const [ROUTER_DIRECTIVES],
     providers: const [HeroService, ROUTER_PROVIDERS])
 @RouteConfig(const [
-// #docregion dashboard-route
+  // #docregion dashboard-route
   const Route(
       path: '/dashboard',
       name: 'Dashboard',
       component: DashboardComponent,
       useAsDefault: true),
-// #enddocregion dashboard-route
+  // #enddocregion dashboard-route
-// #docregion hero-detail-route
+  // #docregion hero-detail-route
   const Route(
       path: '/detail/:id', name: 'HeroDetail', component: HeroDetailComponent),
-// #enddocregion hero-detail-route
+  // #enddocregion hero-detail-route
   const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent)
 ])
 class AppComponent {
   String title = 'Tour of Heroes';
 }
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/app_component_1.dart

@@ -15,12 +15,11 @@ import 'heroes_component.dart';
       <my-heroes></my-heroes>''',
     directives: const [HeroesComponent],
     providers: const [
-// #enddocregion
+      // #enddocregion
       ROUTER_PROVIDERS,
-// #docregion
+      // #docregion
       HeroService
     ])
 class AppComponent {
   String title = 'Tour of Heroes';
 }
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/app_component_2.dart

@@ -10,12 +10,12 @@ import 'heroes_component.dart';
 
 @Component(
     selector: 'my-app',
-// #docregion template
+    // #docregion template
     template: '''
       <h1>{{title}}</h1>
       <a [routerLink]="['Heroes']">Heroes</a>
       <router-outlet></router-outlet>''',
-// #enddocregion template
+    // #enddocregion template
     // #docregion directives-and-providers
     directives: const [ROUTER_DIRECTIVES],
     providers: const [ROUTER_PROVIDERS, HeroService]
@@ -29,4 +29,3 @@ import 'heroes_component.dart';
 class AppComponent {
   String title = 'Tour of Heroes';
 }
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/dashboard_component.css

@@ -1,4 +1,3 @@
-/* #docplaster */
 /* #docregion */
 [class*='col-'] {
   float: left;
@@ -60,4 +59,3 @@ h4 {
 	  min-width: 60px;
 	}
 }
-/* #enddocregion */

public/docs/_examples/toh-5/dart/lib/dashboard_component.dart

@@ -1,5 +1,7 @@
 // #docplaster
 // #docregion
+import 'dart:async';
+
 import 'package:angular2/core.dart';
 // #docregion import-router
 import 'package:angular2/router.dart';
@@ -16,22 +18,25 @@ import 'hero_service.dart';
     // #docregion css
     styleUrls: const ['dashboard_component.css']
     // #enddocregion css
-)
+    )
 // #docregion component
 class DashboardComponent implements OnInit {
   List<Hero> heroes;
-// #docregion ctor
+
+  // #docregion ctor
   final Router _router;
   final HeroService _heroService;
 
   DashboardComponent(this._heroService, this._router);
-// #enddocregion ctor
 
-  ngOnInit() async =>
+  // #enddocregion ctor
-      heroes = (await _heroService.getHeroes()).getRange(1, 5).toList();
+
+  Future<Null> ngOnInit() async {
+    heroes = (await _heroService.getHeroes()).getRange(1, 5).toList();
+  }
 
   // #docregion goto-detail
-  gotoDetail(Hero hero) {
+  void gotoDetail(Hero hero) {
     var link = [
       'HeroDetail',
       {'id': hero.id.toString()}
@@ -40,4 +45,3 @@ class DashboardComponent implements OnInit {
   }
 // #enddocregion goto-detail
 }
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/dashboard_component.html

@@ -1,9 +1,9 @@
 <!-- #docregion -->
 <h3>Top Heroes</h3>
 <div class="grid grid-pad">
-<!-- #docregion click -->
+  <!-- #docregion click -->
   <div *ngFor="let hero of heroes" (click)="gotoDetail(hero)" class="col-1-4" >
-<!-- #enddocregion click -->
+    <!-- #enddocregion click -->
     <div class="module hero">
       <h4>{{hero.name}}</h4>
     </div>

public/docs/_examples/toh-5/dart/lib/dashboard_component_2.dart

@@ -1,5 +1,7 @@
 // #docplaster
 // #docregion imports
+import 'dart:async';
+
 import 'package:angular2/core.dart';
 
 import 'hero.dart';
@@ -9,17 +11,16 @@ import 'hero_service.dart';
 // #docregion component
 @Component(
   selector: 'my-dashboard',
-  templateUrl: 'dashboard_component.html'
+  templateUrl: 'dashboard_component.html')
-)
 class DashboardComponent implements OnInit {
   List<Hero> heroes;
   final HeroService _heroService;
 
   DashboardComponent(this._heroService);
 
-  ngOnInit() async =>
+  Future<Null> ngOnInit() async {
-      heroes = (await _heroService.getHeroes()).getRange(1, 5).toList();
+    heroes = (await _heroService.getHeroes()).getRange(1, 5).toList();
+  }
 
-  gotoDetail(){ /* not implemented yet */}
+  gotoDetail() {/* not implemented yet */}
 }
-// #enddocregion component

public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart

@@ -1,6 +1,7 @@
 // #docplaster
 // #docregion
 // #docregion v2
+import 'dart:async';
 import 'dart:html';
 
 // #docregion import-oninit
@@ -20,37 +21,35 @@ import 'hero_service.dart';
     selector: 'my-hero-detail',
     // #docregion template-url
     templateUrl: 'hero_detail_component.html',
-    // #enddocregion template-url
+    // #enddocregion template-url, v2
-// #enddocregion v2
     styleUrls: const ['hero_detail_component.css']
-// #docregion v2
+    // #docregion v2
-)
+    )
 // #enddocregion extract-template
 // #docregion implement
 class HeroDetailComponent implements OnInit {
-// #enddocregion implement
+  // #enddocregion implement
   Hero hero;
-// #docregion ctor
+  // #docregion ctor
   final HeroService _heroService;
   final RouteParams _routeParams;
 
   HeroDetailComponent(this._heroService, this._routeParams);
-// #enddocregion ctor
+  // #enddocregion ctor
 
-// #docregion ng-oninit
+  // #docregion ng-oninit
-  ngOnInit() async {
+  Future<Null> ngOnInit() async {
     // #docregion get-id
-    var id = int.parse(_routeParams.get('id'));
+    var idString = _routeParams.get('id');
+    var id = int.parse(idString, onError: (_) => null);
     // #enddocregion get-id
-    hero = await (_heroService.getHero(id));
+    if (id != null) hero = await (_heroService.getHero(id));
   }
-// #enddocregion ng-oninit
+  // #enddocregion ng-oninit
 
-// #docregion go-back
+  // #docregion go-back
-  goBack() {
+  void goBack() {
     window.history.back();
   }
-// #enddocregion go-back
+  // #enddocregion go-back
 }
-// #enddocregion v2
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/hero_service.dart

@@ -1,5 +1,3 @@
-// #docplaster
-
 // #docregion
 import 'dart:async';
 
@@ -10,18 +8,16 @@ import 'mock_heroes.dart';
 
 @Injectable()
 class HeroService {
-  Future<List<Hero>> getHeroes() async => HEROES;
+  Future<List<Hero>> getHeroes() async => mockHeroes;
 
   // See the "Take it slow" appendix
   Future<List<Hero>> getHeroesSlowly() {
     return new Future<List<Hero>>.delayed(
-        const Duration(seconds: 2), () => HEROES // 2 seconds
+        const Duration(seconds: 2), () => mockHeroes);
-        );
   }
 
-//#docregion get-hero
+  // #docregion get-hero
   Future<Hero> getHero(int id) async =>
-      HEROES.where((hero) => hero.id == id).first;
+      (await getHeroes()).firstWhere((hero) => hero.id == id);
-//#enddocregion get-hero
+  // #enddocregion get-hero
 }
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/heroes_component.dart

@@ -9,22 +9,19 @@ import 'hero.dart';
 import 'hero_detail_component.dart';
 import 'hero_service.dart';
 
-// #docregion metadata
+// #docregion metadata, heroes-component-renaming
-// #docregion heroes-component-renaming
 @Component(
     selector: 'my-heroes',
-// #enddocregion heroes-component-renaming
+    // #enddocregion heroes-component-renaming
     templateUrl: 'heroes_component.html',
     styleUrls:  const ['heroes_component.css'],
     directives: const [HeroDetailComponent]
-// #docregion heroes-component-renaming
+    // #docregion heroes-component-renaming
 )
-// #enddocregion heroes-component-renaming
+// #enddocregion heroes-component-renaming, metadata
-// #enddocregion metadata
+// #docregion class, heroes-component-renaming
-// #docregion class
-// #docregion heroes-component-renaming
 class HeroesComponent implements OnInit {
-// #enddocregion heroes-component-renaming
+  // #enddocregion heroes-component-renaming
   final Router _router;
   final HeroService _heroService;
   List<Hero> heroes;
@@ -32,7 +29,7 @@ class HeroesComponent implements OnInit {
 
   HeroesComponent(this._heroService, this._router);
 
-  Future getHeroes() async {
+  Future<Null> getHeroes() async {
     heroes = await _heroService.getHeroes();
   }
 
@@ -42,10 +39,7 @@ class HeroesComponent implements OnInit {
 
   void onSelect(Hero hero) { selectedHero = hero; }
 
-  Future gotoDetail() =>
+  Future<Null> gotoDetail() =>
       _router.navigate(['HeroDetail', {'id': selectedHero.id.toString()}]);
-// #docregion heroes-component-renaming
+  // #docregion heroes-component-renaming
 }
-// #enddocregion heroes-component-renaming
-// #enddocregion class
-// #enddocregion

public/docs/_examples/toh-5/dart/lib/heroes_component.html

@@ -17,5 +17,3 @@
   </h2>
   <button (click)="gotoDetail()">View Details</button>
 </div>
-<!-- #enddocregion mini-detail -->
-<!-- #enddocregion -->

public/docs/_examples/toh-5/dart/lib/mock_heroes.dart

@@ -1,6 +1,6 @@
 import 'hero.dart';
 
-final List<Hero> HEROES = [
+final List<Hero> mockHeroes = [
   new Hero(11, 'Mr. Nice'),
   new Hero(12, 'Narco'),
   new Hero(13, 'Bombasto'),

public/docs/_examples/toh-5/dart/web/index.html

@@ -1,10 +1,11 @@
 <!DOCTYPE html>
 <html>
-  <!-- #docregion head -->
+  <!-- #docregion head, base-href -->
-  <!-- #docregion base-href -->
   <head>
-    <base href="/">   <!-- For testing using pub serve directly -->
+    <!-- For testing using pub serve directly use: -->
-    <!-- base href="/dart/web/" --> <!-- For testing in WebStorm -->
+    <base href="/">
+    <!-- For testing in WebStorm use: -->
+    <!-- base href="/dart/web/" -->
     <!-- #enddocregion base-href -->
     <title>Angular 2 Tour of Heroes</title>
     <meta name="viewport" content="width=device-width, initial-scale=1">

public/docs/_examples/toh-5/dart/web/main.dart

@@ -2,6 +2,6 @@ import 'package:angular2/platform/browser.dart';
 
 import 'package:angular2_tour_of_heroes/app_component.dart';
 
-main() {
+void main() {
   bootstrap(AppComponent);
 }

public/docs/_examples/toh-5/dart/web/styles_1.css

@@ -0,0 +1,24 @@
+/* #docregion toh-excerpt */
+/* Master Styles */
+h1 {
+  color: #369; 
+  font-family: Arial, Helvetica, sans-serif;   
+  font-size: 250%;
+}
+h2, h3 { 
+  color: #444;
+  font-family: Arial, Helvetica, sans-serif;   
+  font-weight: lighter;
+}
+body { 
+  margin: 2em; 
+}
+body, input[text], button { 
+  color: #888; 
+  font-family: Cambria, Georgia; 
+}
+/* . . . */
+/* everywhere else */
+* { 
+  font-family: Arial, Helvetica, sans-serif; 
+}

public/docs/ts/latest/tutorial/toh-pt5.jade

@@ -87,20 +87,22 @@ code-example(language="bash").
   我们继续构建《英雄指南》，应用也会保持运行并自动更新。
 
   ## Action plan
+  
   ## 行动计划
-  Here's our plan
   
-  下面是我们的计划
+  Here's our plan:
   
-  * turn `AppComponent` into an application shell that only handles navigation,
+  下面是我们的计划：
+  
+  * Turn `AppComponent` into an application shell that only handles navigation
   * 把`AppComponent`变成应用程序的“壳”，它只处理导航，
-  * relocate the *Heroes* concerns within the current `AppComponent` to a separate `HeroesComponent`,
+  * Relocate the *Heroes* concerns within the current `AppComponent` to a separate `HeroesComponent`
   * 把现在由`AppComponent`关注的*英雄们*移到一个独立的`HeroesComponent`中，
-  * add routing,
+  * Add routing
-  * 添加路由，
+  * 添加路由
-  * create a new `DashboardComponent`,
+  * Create a new `DashboardComponent`
-  * 添加一个新的`DashboardComponent`组件，
+  * 添加一个新的`DashboardComponent`组件
-  * tie the *Dashboard* into the navigation structure.
+  * Tie the *Dashboard* into the navigation structure
   * 把*仪表盘*加入导航结构中。
 
 .l-sub-section
@@ -137,15 +139,15 @@ code-example(language="bash").
   `AppComponent`的职责已经被移交给`HeroesComponent`了。
   与其把`AppComponent`中所有的东西都搬过去，不如索性把它改名为`HeroesComponent`，然后单独创建一个新的`AppComponent`壳。
   
-  The steps are:
+  The steps are to rename:
   
-  步骤如下：
+  改名的步骤如下：
-  * rename `app.component.ts` file to `heroes.component.ts`.
+  * `app.component.ts` file to `heroes.component.ts`
-  * 把`app.component.ts`文件改名为`heroes.component.ts`。
+  * 把`app.component.ts`文件改名为`heroes.component.ts`
-  * rename the `AppComponent` class to `HeroesComponent`.
+  * `AppComponent` class to `HeroesComponent`
-  * 把`AppComponent`类改名为`HeroesComponent`。
+  * 把`AppComponent`类改名为`HeroesComponent`
-  * rename the selector `my-app` to `my-heroes`.
+  * Selector `my-app` to `my-heroes`
-  * 把`my-app`选择器改名为`my-heroes`。
+  * 把`my-app`选择器改名为`my-heroes`
 
 :marked
 +makeExample('toh-5/ts/app/heroes.component.ts', 'heroes-component-renaming', 'app/heroes.component.ts (showing renamings only)')(format=".")
@@ -934,17 +936,15 @@ figure.image-display
   1. *Set* the component metadata's `templateUrl` and `styleUrls` properties to refer to both files.
   1. *设置*组件元数据的`templateUrl`和`styleUrls`属性，来分别引用这两个文件。
   
-  We no longer display the `HeroDetailComponent` in the `HeroesComponent` template because we're navigating to it.
+  Because the template for `HeroesComponent` no longer uses `HeroDetailComponent` 
-  So we can remove it from the metadata `directives` array. The `directives` array is now empty so we delete it.
+  directly — instead using the router to _navigate_ to it — we can 
-  We might as well delete the `HeroDetailComponent` import statement too.
+  remove `HeroDetailComponent` from the directives list. That
+  list is now empty, so we can remove the `directives` property. The revised
+  `@Component` looks like this:
   
-  在`HeroesComponent`模板中，不需要再显示`HeroDetailComponent`，因为我们要导航到它。
+  由于`HeroesComponent`的模板中不再直接使用`HeroDetailComponent`，而是通过路由_导航_到它，
-  所以我们可以从元数据的`directives`数组中移除它。`directives`数组现在没东西了，因此我们也把它删掉。
+  于是我们就可以从`HeroDetailComponent`的指令列表中把它移除了。指令列表现在是空的，所以我们干脆把`directives`属性也移除。
-  我们也同样可以删掉`import` `HeroDetailComponent`的语句。
+  修改过的`@Component`看起来像这样：
-  
-  The revised `@Component` looks like this:
-  
-  修改过的`@Component`是这样的：
 
 +makeExample('toh-5/ts/app/heroes.component.ts', 'metadata', 'app/heroes.component.ts (revised metadata)')(format=".")
 :marked
@@ -1104,9 +1104,9 @@ figure.image-display
   如果在根目录下没有一个名叫`styles.css`的文件，就添加它。
   确保它包含[这里给出的主样式](!{styles_css})。
 
-  Also ensure this stylesheet is referenced in the traditional manner within `index.html`.
+  If necessary, also edit `index.html` to refer to this stylesheet.
   
-  同时确保这个样式表在`index.html`中被使用传统方式引用了。
+  如有必要，也可以编辑`index.html`来引用这个样式表。
   
 +makeExample('toh-5/ts/index.html','css', 'index.html (link ref)')(format=".")
 :marked
@@ -1124,7 +1124,7 @@ figure.image-display
   ## 应用结构和代码
   
 p.
-  Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this part.
+  Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this chapter.
   Verify that we have the following structure:
 
 p.

tools/api-builder/angular.io-package/index.js

@@ -51,6 +51,9 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe
     '___esModule',
     '___core_private_types__',
     '___platform_browser_private__',
+    '___platform_browser_private_types__',
+    '___platform_browser_dynamic_private__',
+    '___platform_browser_dynamic_private_types__',
     '___compiler_private__',
     '__core_private__',
     '___core_private__'