docs(architecture/dart): proofread, updated Dart/TS app and jade

closes #1807
- e2e tests now also cover the tax calculator.
- Dart app updated to match TS (it had no sales tax calculator).
- TS sample source cleanup (e.g. removed many unnecessary `docregions`).
- Prose updated to include @kwalrath's revisions from a while ago, Ward's comments, and
some of my edits as well.

Contributes to #1598 and #1508.

Author: chalin

public/docs/_examples/architecture/dart/lib/app_component.dart

@@ -0,0 +1,15 @@
+// #docregion import
+import 'package:angular2/core.dart';
+// #enddocregion import
+
+import 'hero_list_component.dart';
+import 'sales_tax_component.dart';
+
+@Component(
+    selector: 'my-app',
+    template: '''
+      <hero-list></hero-list>
+      <sales-tax></sales-tax>''',
+    directives: const [HeroListComponent, SalesTaxComponent])
+// #docregion export
+class AppComponent { }

public/docs/_examples/architecture/dart/lib/backend_service.dart

@@ -1,24 +1,28 @@
-// #docregion
+import 'dart:async';
+
 import 'package:angular2/core.dart';
 
 import 'hero.dart';
 import 'logger_service.dart';
 
 @Injectable()
 class BackendService {
+  static final _mockHeroes = [
+    new Hero('Windstorm', 'Weather mastery'),
+    new Hero('Mr. Nice', 'Killing them with kindness'),
+    new Hero('Magneta', 'Manipulates metalic objects')
+  ];
+
   final Logger _logger;
-  List getAll(type) {
-    // TODO get from the database and return as a promise
-    if (type == Hero) {
-      return [
-        new Hero('Windstorm', power: 'Weather mastery'),
-        new Hero('Mr. Nice', power: 'Killing them with kindness'),
-        new Hero('Magneta', power: 'Manipulates metalic objects')
-      ];
-    }
-    _logger.error('Cannot get object of this type');
-    throw new ArgumentError("TODO: put log content here");
-  }
 
   BackendService(Logger this._logger);
+
+  Future<List> getAll(type) {
+    // TODO get from the database
+    if (type == Hero) return new Future.value(_mockHeroes);
+
+    var msg = 'Cannot get object of this type';
+    _logger.error(msg);
+    throw new Exception(msg);
+  }
 }

public/docs/_examples/architecture/dart/lib/hero.dart

@@ -1,11 +1,7 @@
-// #docregion
 class Hero {
   static int _nextId = 1;
-  int id;
-  String name;
-  String power;
+  final int id;
+  String name, power;
 
-  Hero(this.name, {this.power}) {
-    id = _nextId++;
-  }
+  Hero(this.name, [this.power = '']) : id = _nextId++;
 }

public/docs/_examples/architecture/dart/lib/hero_detail_component.dart

@@ -1,9 +1,11 @@
-// #docregion
 import 'package:angular2/core.dart';
 
 import 'hero.dart';
 
-@Component(selector: 'hero-detail', templateUrl: 'hero_detail_component.html')
+@Component(
+    selector: 'hero-detail',
+    templateUrl: 'hero_detail_component.html')
 class HeroDetailComponent {
-  @Input() Hero hero;
+  @Input()
+  Hero hero;
 }

public/docs/_examples/architecture/dart/lib/hero_detail_component.html

@@ -2,8 +2,8 @@
 <h4>{{hero.name}} Detail</h4>
 <div>Id: {{hero.id}}</div>
 <div>Name:
-  <!-- #docregion ng-model -->
-  <input [(ngModel)]="hero.name"></div>
-  <!-- #enddocregion ng-model -->
-<div>Power:<input [(ngModel)]="hero.power">
+  <!-- #docregion ngModel -->
+  <input [(ngModel)]="hero.name">
+  <!-- #enddocregion ngModel -->
 </div>
+<div>Power:<input [(ngModel)]="hero.power"></div>

public/docs/_examples/architecture/dart/lib/hero_list_component.dart

@@ -1,37 +1,35 @@
-// #docplaster
 import 'package:angular2/core.dart';
 
 import 'hero.dart';
 import 'hero_detail_component.dart';
 import 'hero_service.dart';
 
 // #docregion metadata
-// #docregion providers
 @Component(
-// #enddocregion providers
     selector: 'hero-list',
     templateUrl: 'hero_list_component.html',
     directives: const [HeroDetailComponent],
-// #docregion providers
-    providers: const [HeroService])
-// #enddocregion providers
-// #enddocregion metadata
-/*
-// #docregion metadata, providers
-class HeroListComponent { ... }
-// #enddocregion metadata, providers
-*/
+    // #docregion providers
+    providers: const [HeroService]
+    // #enddocregion providers
+    )
 // #docregion class
-class HeroListComponent {
+class HeroListComponent implements OnInit {
+  // #enddocregion metadata
   List<Hero> heroes;
   Hero selectedHero;
-// #docregion ctor
-  HeroListComponent(HeroService heroService) {
-    heroes = heroService.getHeroes();
+  // #docregion ctor
+  final HeroService _heroService;
+
+  HeroListComponent(this._heroService);
+  // #enddocregion ctor
+
+  void ngOnInit() {
+    heroes = _heroService.getHeroes();
   }
-// #enddocregion ctor
-  selectHero(Hero hero) {
+
+  void selectHero(Hero hero) {
     selectedHero = hero;
   }
+  // #docregion metadata
 }
-// #enddocregion class

public/docs/_examples/architecture/dart/lib/hero_list_component.html

@@ -1,8 +1,11 @@
 <!-- #docregion -->
 <h2>Hero List</h2>
 
-<div *ngFor="let hero of heroes" (click)="selectHero(hero)">
-  {{hero.name}}
-</div>
+<p><i>Pick a hero from the list</i></p>
+<ul>
+  <li *ngFor="let hero of heroes" (click)="selectHero(hero)">
+    {{hero.name}}
+  </li>
+</ul>
 
 <hero-detail *ngIf="selectedHero != null" [hero]="selectedHero"></hero-detail>

public/docs/_examples/architecture/dart/lib/hero_list_component_1.html

@@ -1,10 +1,9 @@
 <!--#docregion binding  -->
-<div ... >{{hero.name}}</div>
-<hero-detail ... [hero]="selectedHero"></hero-detail>
-<div ... (click)="selectHero(hero)">...</div>
+<li>{{hero.name}}</li>
+<hero-detail [hero]="selectedHero"></hero-detail>
+<li (click)="selectHero(hero)"></li>
 <!--#enddocregion binding -->
 
 <!--#docregion structural  -->
-<div *ngFor="let hero of heroes" ...>...</div>
-<hero-detail *ngIf="selectedHero != null" ...></hero-detail>
-<!--#enddocregion structural -->
+<li *ngFor="let hero of heroes"></li>
+<hero-detail *ngIf="selectedHero != null"></hero-detail>

public/docs/_examples/architecture/dart/lib/hero_service.dart

@@ -4,16 +4,20 @@ import 'backend_service.dart';
 import 'hero.dart';
 import 'logger_service.dart';
 
-// #docregion class
 @Injectable()
+// #docregion class
 class HeroService {
   final BackendService _backendService;
   final Logger _logger;
-  HeroService(Logger this._logger, BackendService this._backendService);
+  final List<Hero> heroes = [];
+
+  HeroService(this._logger, this._backendService);
+
   List<Hero> getHeroes() {
-    List<Hero> heroes = _backendService.getAll(Hero);
-    _logger.log('Got ${heroes.length} heroes from the server.');
+    _backendService.getAll(Hero).then((heroes) {
+      _logger.log('Fetched ${heroes.length} heroes.');
+      this.heroes.addAll(heroes); // fill cache
+    });
     return heroes;
   }
 }
-// #enddocregion class

public/docs/_examples/architecture/dart/lib/logger_service.dart

@@ -1,16 +1,11 @@
-// #docregion
 import 'dart:html';
 
 import 'package:angular2/core.dart';
 
-/// A service for logging messages of various types.
-///
-/// We could switch this implementation to use package:logging.
 @Injectable()
+// #docregion class
 class Logger {
   void log(Object msg) => window.console.log(msg);
-
   void error(Object msg) => window.console.error(msg);
-
   void warn(Object msg) => window.console.warn(msg);
 }