docs(toh-5): TS/Dart review, and Dart resync (#2115)

* docs(toh-5): review and update/resync Dart

**NOTE: run `gulp add-example-boilerplate` after pulling in the
commit.**

This is preparatory work for #2035.
As part of the the chapter review, the Dart .jade was enhanced to use
Jade extends (#2018).
By the same token it contributed to a post-RC5 resync (#2077). Other
key changes:

Dart and TS code:
- Eliminated `styles.1.css` in favor of docregions in `styles.css`.
- `docregion` tags renamed in a few places.
- **No other code changes**.

TS prose
- Fixed: misnamed variable `routing` -> `appRoutes`.
- All other changes are **minor copy edits**, or changes to support
Dart via Jade extends.

Diff of generated HTML for TS chapter was inspected to ensure only
minor copy edits prevailed (i.e., that the support for Jade extends had
no impact on the generated HTML).

* docs(toh-5): edits after doing tutorial

- Some adjustments following actually doing the tutorial. In some cases code shown (e.g. this is what file foo should look like now) didn't match what the user would have. E.g., lingering @input on the hero property.
- Fixed some lingering deprecated-router prose elements on TS side (e.g., still referring to a route by the old string names like `HeroDetail`).
- Added extra step to `app.component.ts` creation rather than having a critical-call-out later on.
- Reorder some prose for better harmony between TS and Dart prose (also improves the flow).
- Moved the `styleUrls` call-out to the point of first use.

* post-review changes

* more post-review changes

* toh-6 cache update

Author: chalin

public/_includes/_util-fns.jade

@@ -222,8 +222,8 @@ script.
 -   // E.g. of a project relative path is 'app/main.ts'
 -   if (ex.title === null || ex.title === undefined) {
 -     // Title is not given so take it to be ex.filePath.
--     // Is title like styles.1.css? Then drop the '.1' qualifier:
--     var matches = ex.filePath.match(/^(.*)\.\d(\.\w+)$/);
+-     // Title like styles.1.css or foo_1.dart? Then drop the '.1' or '_1' qualifier:
+-     var matches = ex.filePath.match(/^(.*)[\._]\d(\.\w+)$/);
 -     ex.title = matches ? matches[1] + matches[2] : ex.filePath;
 -   }
 -   ex.filePath = getExampleName() + '/' + _docsFor + '/' + ex.filePath;

public/docs/_examples/styles.css

@@ -1,4 +1,4 @@
-/* #docregion , quickstart */
+/* #docregion , quickstart, toh */
 /* Master Styles */
 h1 {
   color: #369;
@@ -18,6 +18,7 @@ body, input[text], button {
   color: #888;
   font-family: Cambria, Georgia;
 }
+/* #enddocregion toh */
 a {
   cursor: pointer;
   cursor: hand;
@@ -137,7 +138,7 @@ nav a.active {
   margin-right: .8em;
   border-radius: 4px 0 0 4px;
 }
-
+/* #docregion toh */
 /* everywhere else */
 * {
   font-family: Arial, Helvetica, sans-serif;

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

@@ -1,45 +1,51 @@
 // #docplaster
 // #docregion
 import 'package:angular2/core.dart';
+// #docregion import-router
 import 'package:angular2/router.dart';
+// #enddocregion import-router
 
-import 'package:angular2_tour_of_heroes/heroes_component.dart';
-import 'package:angular2_tour_of_heroes/hero_service.dart';
-import 'package:angular2_tour_of_heroes/dashboard_component.dart';
-// #docregion hero-detail-import
-import 'package:angular2_tour_of_heroes/hero_detail_component.dart';
-// #enddocregion hero-detail-import
+import 'dashboard_component.dart';
+import 'hero_detail_component.dart';
+import 'hero_service.dart';
+import 'heroes_component.dart';
 
 @Component(
     selector: 'my-app',
-    // #docregion template
+    // #docregion template, template-v3
     template: '''
       <h1>{{title}}</h1>
       <nav>
         <a [routerLink]="['Dashboard']">Dashboard</a>
         <a [routerLink]="['Heroes']">Heroes</a>
       </nav>
       <router-outlet></router-outlet>''',
-    // #enddocregion template
-    // #docregion style-urls
+    // #enddocregion template, template-v3
+    // #docregion styleUrls
     styleUrls: const ['app_component.css'],
-    // #enddocregion style-urls
+    // #enddocregion styleUrls
+    // #docregion directives-and-providers
     directives: const [ROUTER_DIRECTIVES],
     providers: const [HeroService, ROUTER_PROVIDERS])
+// #enddocregion directives-and-providers
+// #docregion heroes
 @RouteConfig(const [
-  // #docregion dashboard-route
+  // #enddocregion heroes
+  // #docregion dashboard
   const Route(
       path: '/dashboard',
       name: 'Dashboard',
       component: DashboardComponent,
       useAsDefault: true),
-  // #enddocregion dashboard-route
-  // #docregion hero-detail-route
+  // #enddocregion dashboard
+  // #docregion hero-detail
   const Route(
       path: '/detail/:id', name: 'HeroDetail', component: HeroDetailComponent),
-  // #enddocregion hero-detail-route
+  // #enddocregion hero-detail
+  // #docregion heroes
   const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent)
 ])
+// #enddocregion heroes
 class AppComponent {
   String title = 'Tour of Heroes';
 }

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

@@ -1,25 +1,40 @@
 // #docplaster
-// #docregion
+// #docregion , v2
 import 'package:angular2/core.dart';
-// #enddocregion
-import 'package:angular2/router.dart'; // for testing only
+// #enddocregion ,
+// #docregion v2
+import 'package:angular2/router.dart';
 // #docregion
 
 import 'hero_service.dart';
 import 'heroes_component.dart';
 
+// #enddocregion v2
 @Component(
     selector: 'my-app',
     template: '''
       <h1>{{title}}</h1>
       <my-heroes></my-heroes>''',
     directives: const [HeroesComponent],
-    providers: const [
-      // #enddocregion
-      ROUTER_PROVIDERS,
-      // #docregion
-      HeroService
-    ])
+    providers: const [HeroService])
+// #enddocregion ,
+class Bogus {}
+
+// #docregion v2
+@Component(
+    selector: 'my-app',
+    // #docregion template-v2
+    template: '''
+      <h1>{{title}}</h1>
+      <a [routerLink]="['Heroes']">Heroes</a>
+      <router-outlet></router-outlet>''',
+    // #enddocregion template-v2
+    directives: const [ROUTER_DIRECTIVES],
+    providers: const [HeroService, ROUTER_PROVIDERS])
+@RouteConfig(const [
+  const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent)
+])
+// #docregion ,
 class AppComponent {
   String title = 'Tour of Heroes';
 }

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

@@ -12,9 +12,9 @@ import 'hero_service.dart';
 
 @Component(
     selector: 'my-dashboard',
-    // #docregion template-url
+    // #docregion templateUrl
     templateUrl: 'dashboard_component.html',
-    // #enddocregion template-url
+    // #enddocregion templateUrl
     // #docregion css
     styleUrls: const ['dashboard_component.css']
     // #enddocregion css
@@ -35,13 +35,13 @@ class DashboardComponent implements OnInit {
     heroes = (await _heroService.getHeroes()).skip(1).take(4).toList();
   }
 
-  // #docregion goto-detail
+  // #docregion gotoDetail
   void gotoDetail(Hero hero) {
     var link = [
       'HeroDetail',
       {'id': hero.id.toString()}
     ];
     _router.navigate(link);
   }
-// #enddocregion goto-detail
+// #enddocregion gotoDetail
 }

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

@@ -22,5 +22,5 @@ class DashboardComponent implements OnInit {
     heroes = (await _heroService.getHeroes()).skip(1).take(4).toList();
   }
 
-  gotoDetail() {/* not implemented yet */}
+  gotoDetail(Hero hero) {/* not implemented yet */}
 }

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

@@ -1,30 +1,28 @@
 // #docplaster
 // #docregion , v2
+// #docregion added-imports
 import 'dart:async';
-import 'dart:html';
+import 'dart:html' show window;
 
-// #docregion import-oninit
+// #enddocregion added-imports
 import 'package:angular2/core.dart';
-// #enddocregion import-oninit
-// #docregion import-route-params
+// #docregion added-imports
 import 'package:angular2/router.dart';
-// #enddocregion import-route-params
 
+// #enddocregion added-imports
 import 'hero.dart';
-// #docregion import-hero-service
+// #docregion added-imports
 import 'hero_service.dart';
-// #enddocregion import-hero-service
+// #enddocregion added-imports
 
-// #docregion extract-template
 @Component(
     selector: 'my-hero-detail',
-    // #docregion template-url
+    // #docregion templateUrl
     templateUrl: 'hero_detail_component.html',
-    // #enddocregion template-url, v2
+    // #enddocregion templateUrl, v2
     styleUrls: const ['hero_detail_component.css']
     // #docregion v2
     )
-// #enddocregion extract-template
 // #docregion implement
 class HeroDetailComponent implements OnInit {
   // #enddocregion implement
@@ -36,19 +34,17 @@ class HeroDetailComponent implements OnInit {
   HeroDetailComponent(this._heroService, this._routeParams);
   // #enddocregion ctor
 
-  // #docregion ng-oninit
+  // #docregion ngOnInit
   Future<Null> ngOnInit() async {
-    // #docregion get-id
     var idString = _routeParams.get('id');
-    var id = int.parse(idString, onError: (_) => null);
-    // #enddocregion get-id
+    var id = int.parse(idString ?? '', onError: (_) => null);
     if (id != null) hero = await (_heroService.getHero(id));
   }
-  // #enddocregion ng-oninit
+  // #enddocregion ngOnInit
 
-  // #docregion go-back
+  // #docregion goBack
   void goBack() {
     window.history.back();
   }
-  // #enddocregion go-back
+  // #enddocregion goBack
 }

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

@@ -16,8 +16,8 @@ class HeroService {
         const Duration(seconds: 2), () => mockHeroes);
   }
 
-  // #docregion get-hero
+  // #docregion getHero
   Future<Hero> getHero(int id) async =>
       (await getHeroes()).firstWhere((hero) => hero.id == id);
-  // #enddocregion get-hero
+  // #enddocregion getHero
 }

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

@@ -6,27 +6,28 @@ import 'package:angular2/core.dart';
 import 'package:angular2/router.dart';
 
 import 'hero.dart';
-import 'hero_detail_component.dart';
 import 'hero_service.dart';
 
-// #docregion metadata, heroes-component-renaming
+// #docregion metadata, renaming
 @Component(
     selector: 'my-heroes',
-    // #enddocregion heroes-component-renaming
+    // #enddocregion renaming
     templateUrl: 'heroes_component.html',
-    styleUrls: const ['heroes_component.css'],
-    directives: const [HeroDetailComponent])
-// #docregion heroes-component-renaming
-// #enddocregion heroes-component-renaming, metadata
-// #docregion class, heroes-component-renaming
+    styleUrls: const ['heroes_component.css']
+// #docregion renaming
+)
+// #enddocregion metadata
+// #docregion class
 class HeroesComponent implements OnInit {
-  // #enddocregion heroes-component-renaming
+  // #enddocregion renaming
   final Router _router;
   final HeroService _heroService;
   List<Hero> heroes;
   Hero selectedHero;
 
+  // #docregion renaming
   HeroesComponent(this._heroService, this._router);
+  // #enddocregion renaming
 
   Future<Null> getHeroes() async {
     heroes = await _heroService.getHeroes();
@@ -44,5 +45,5 @@ class HeroesComponent implements OnInit {
         'HeroDetail',
         {'id': selectedHero.id.toString()}
       ]);
-  // #docregion heroes-component-renaming
+  // #docregion renaming
 }