docs(dependency-injection): revise Dart and TS code and prose

public/docs/_examples/dependency-injection/dart/lib/app_component.dart

@@ -1,16 +1,12 @@
-// #docplaster
-// #docregion
-// #docregion imports
 import 'package:angular2/core.dart';
 
 import 'app_config.dart';
 import 'car/car_component.dart';
 import 'heroes/heroes_component.dart';
 import 'logger_service.dart';
 import 'user_service.dart';
-//PENDING: check whether we intend to hide injector_component.dart & providers_component.dart; if so, change docregion name?
-// #enddocregion imports
 import 'injector_component.dart';
+import 'test_component.dart';
 import 'providers_component.dart';
 
 @Component(
@@ -31,21 +27,21 @@ import 'providers_component.dart';
       CarComponent,
       HeroesComponent,
       InjectorComponent,
+      TestComponent,
       ProvidersComponent
     ],
     // #docregion providers
     providers: const [
-      Logger,
-      UserService,
-      const Provider(AppConfig, useValue: config1)]
+      Logger, UserService,
+      const Provider(APP_CONFIG, useFactory: heroDiConfigFactory)]
     // #enddocregion providers
 )
 class AppComponent {
   final UserService _userService;
   final String title;
 
   // #docregion ctor
-  AppComponent(AppConfig config, this._userService)
+  AppComponent(@Inject(APP_CONFIG) AppConfig config, this._userService)
       : title = config.title;
   // #enddocregion ctor
 
@@ -61,7 +57,6 @@ class AppComponent {
     return _userService.user;
   }
 
-  String get userInfo => 'Current user, ${user.name}, is'
-      '${isAuthorized ? "" : " not"} authorized. ';
+  String get userInfo => 'Current user, ${user.name}, is' +
+    (isAuthorized ? '' : ' not') + ' authorized. ';
 }
-// #enddocregion

public/docs/_examples/dependency-injection/dart/lib/app_component_1.dart

@@ -16,13 +16,3 @@ import 'heroes/heroes_component_1.dart';
 class AppComponent {
   final String title = 'Dependency Injection';
 }
-// #enddocregion
-
-/*
-//#docregion ctor-di-fail
-// FAIL! Injectable `config` is not a class!
-AppComponent(HeroService heroService, Map config) {
-  title = config['title'];
-}
-//#enddocregion ctor-di-fail
-*/

public/docs/_examples/dependency-injection/dart/lib/app_component_2.dart

@@ -21,13 +21,16 @@ import 'logger_service.dart';
     ],
     providers: const [
       Logger,
-      const Provider(AppConfig, useValue: config1)
-    ])
+      // #docregion providers
+      const Provider(APP_CONFIG, useValue: heroDiConfig)
+      // #enddocregion providers
+    ]
+)
 class AppComponent {
   final String title;
 
   // #docregion ctor
-  AppComponent(AppConfig config)
-      : title = config.title;
-  // #enddocregion
+  AppComponent(@Inject(APP_CONFIG) Map config)
+      : title = config['title'];
+  // #enddocregion ctor
 }

public/docs/_examples/dependency-injection/dart/lib/app_config.dart

@@ -1,17 +1,27 @@
-// #docregion
 // #docregion token
 import 'package:angular2/core.dart';
 
-//#docregion const-class
-@Injectable()
-class AppConfig {
-  final apiEndpoint;
-  final String title;
+const APP_CONFIG = const OpaqueToken('app.config');
+// #enddocregion token
+
+// #docregion config
+const Map heroDiConfig = const <String,String>{
+  'apiEndpoint' : 'api.heroes.com',
+  'title' : 'Dependency Injection'
+};
+// #enddocregion config
 
-  const AppConfig(this.apiEndpoint, this.title);
+// #docregion config-alt
+class AppConfig {
+  String apiEndpoint;
+  String title;
 }
-//#enddocregion const-class
 
-//#docregion const-object
-const config1 = const AppConfig('api.heroes.com', 'Dependency Injection');
-//#enddocregion const-object
+AppConfig heroDiConfigFactory() => new AppConfig()
+  ..apiEndpoint = 'api.heroes.com'
+  ..title = 'Dependency Injection';
+// #enddocregion config-alt
+
+const appConfigProvider = const Provider(APP_CONFIG,
+  useFactory: heroDiConfigFactory,
+  deps: const []);

public/docs/_examples/dependency-injection/dart/lib/car/car.dart

@@ -1,21 +1,19 @@
-// #docregion
 import 'package:angular2/core.dart';
 
 @Injectable()
-// #docregion engine
 class Engine {
-  final int cylinders = 4;
+  final int cylinders;
+
+  Engine() : cylinders = 4;
+  Engine.withCylinders(this.cylinders);
 }
-// #enddocregion engine
 
 @Injectable()
-// #docregion tires
 class Tires {
   String make = 'Flintstone';
   String model = 'Square';
 }
 
-// #enddocregion tires
 @Injectable()
 class Car {
   //#docregion car-ctor
@@ -24,11 +22,10 @@ class Car {
   String description = 'DI';
 
   Car(this.engine, this.tires);
-
   // #enddocregion car-ctor
 
   // Method using the engine and tires
-  String drive() => '$description car with ${engine.cylinders} cylinders'
-      ' and ${tires.make} tires.';
+  String drive() => '$description car with '
+      '${engine.cylinders} cylinders and '
+      '${tires.make} tires.';
 }
-// #enddocregion car

public/docs/_examples/dependency-injection/dart/lib/car/car_creations.dart

@@ -3,50 +3,39 @@
 import 'car.dart';
 
 ///////// example 1 ////////////
-Car simpleCar() {
+Car simpleCar() =>
   // #docregion car-ctor-instantiation
   // Simple car with 4 cylinders and Flintstone tires.
-  var car = new Car(new Engine(), new Tires());
+  new Car(new Engine(), new Tires())
   // #enddocregion car-ctor-instantiation
-  car.description = 'Simple';
-  return car;
-}
+  ..description = 'Simple';
+
 ///////// example 2 ////////////
 
 // #docregion car-ctor-instantiation-with-param
-class Engine2 implements Engine {
-  final int cylinders;
-
-  Engine2(this.cylinders);
+class Engine2 extends Engine {
+  Engine2(cylinders) : super.withCylinders(cylinders);
 }
-//#enddocregion car-ctor-instantiation-with-param
 
-Car superCar() {
-//#docregion car-ctor-instantiation-with-param
+Car superCar() =>
   // Super car with 12 cylinders and Flintstone tires.
-var bigCylinders = 12;
-var car = new Car(new Engine2(bigCylinders), new Tires());
+  new Car(new Engine2(12), new Tires())
+  ..description = 'Super';
 // #enddocregion car-ctor-instantiation-with-param
-  car.description = 'Super';
-  return car;
-}
+
 /////////// example 3 //////////
 
 // #docregion car-ctor-instantiation-with-mocks
 class MockEngine extends Engine {
-  final int cylinders = 8;
+  MockEngine() : super.withCylinders(8);
 }
 
 class MockTires extends Tires {
-  String make = 'YokoGoodStone';
+  MockTires() { make = 'YokoGoodStone'; }
 }
 
-//#enddocregion car-ctor-instantiation-with-mocks
-Car testCar() {
-//#docregion car-ctor-instantiation-with-mocks
+Car testCar() =>
   // Test car with 8 cylinders and YokoGoodStone tires.
-var car = new Car(new MockEngine(), new MockTires());
+  new Car(new MockEngine(), new MockTires())
+  ..description = 'Test';
 // #enddocregion car-ctor-instantiation-with-mocks
-  car.description = 'Test';
-  return car;
-}

public/docs/_examples/dependency-injection/dart/lib/car/car_factory.dart

@@ -3,10 +3,9 @@ import 'car.dart';
 
 // BAD pattern!
 class CarFactory {
-  Car createCar() {
-    return new Car(createEngine(), createTires())
+  Car createCar() =>
+      new Car(createEngine(), createTires())
         ..description = 'Factory';
-  }
 
   Engine createEngine() => new Engine();
   Tires createTires() => new Tires();

public/docs/_examples/dependency-injection/dart/lib/car/car_injector.dart

@@ -1,5 +1,3 @@
-// #docplaster
-//#docregion
 import 'package:angular2/core.dart';
 
 import '../logger_service.dart';
@@ -9,28 +7,21 @@ import 'car.dart';
 Car useInjector() {
   ReflectiveInjector injector;
   // #enddocregion injector
-
   /*
   // #docregion injector-no-new
-  // Cannot 'new' an ReflectiveInjector like this!
-  var injector = new ReflectiveInjector([Car, Engine, Tires, Logger]);
+  // Cannot instantiate an ReflectiveInjector like this!
+  var injector = new ReflectiveInjector([Car, Engine, Tires]);
   // #enddocregion injector-no-new
   */
-
-  //#docregion injector
-
-  //#docregion injector-create-and-call
-  injector = ReflectiveInjector.resolveAndCreate([Car, Engine, Tires, Logger]);
+  // #docregion injector, injector-create-and-call
+  injector = ReflectiveInjector.resolveAndCreate([Car, Engine, Tires]);
   // #docregion injector-call
   var car = injector.get(Car);
-  //#enddocregion injector-call
-  //#enddocregion injector-create-and-call
-
+  // #enddocregion injector-call, injector-create-and-call
   car.description = 'Injector';
+
+  injector = ReflectiveInjector.resolveAndCreate([Logger]);
   var logger = injector.get(Logger);
   logger.log('Injector car.drive() said: ' + car.drive());
   return car;
 }
-//#enddocregion injector
-
-//#enddocregion

public/docs/_examples/dependency-injection/dart/lib/car/car_no_di.dart

@@ -17,6 +17,7 @@ class Car {
 
   // Method using the engine and tires
   String drive() => '$description car with '
-      '${engine.cylinders} cylinders and ${tires.make} tires.';
+    '${engine.cylinders} cylinders and '
+    '${tires.make} tires.';
 }
 //#enddocregion car

public/docs/_examples/dependency-injection/dart/lib/heroes/hero.dart

@@ -1,6 +1,8 @@
 // #docregion
 class Hero {
-  num id;
-  String name;
-  bool isSecret = false;
+  final int id;
+  final String name;
+  final bool isSecret;
+
+  Hero(this.id, this.name, [this.isSecret = false]);
 }

public/docs/_examples/dependency-injection/dart/lib/heroes/hero_list_component.dart

@@ -15,6 +15,7 @@ class HeroListComponent {
   final List<Hero> heroes;
 
   // #docregion ctor-signature
-  HeroListComponent(HeroService heroService) : heroes = heroService.getHeroes();
+  HeroListComponent(HeroService heroService)
   // #enddocregion ctor-signature
+    : heroes = heroService.getHeroes();
 }

public/docs/_examples/dependency-injection/dart/lib/heroes/hero_list_component_2.dart

@@ -1,8 +1,16 @@
+// #docplaster
 // #docregion
 import 'package:angular2/core.dart';
 
 import 'hero.dart';
+// #enddocregion
+import 'hero_service_1.dart';
+/*
+// #docregion
 import 'hero_service.dart';
+// #enddocregion
+*/
+// #docregion
 
 @Component(
     selector: 'hero-list',

public/docs/_examples/dependency-injection/dart/lib/heroes/hero_service_1.dart

@@ -1,7 +1,10 @@
 // #docregion
+import 'package:angular2/core.dart';
+
 import 'hero.dart';
 import 'mock_heroes.dart';
 
+@Injectable()
 class HeroService {
   List<Hero> getHeroes() => HEROES;
 }

public/docs/_examples/dependency-injection/dart/lib/heroes/hero_service_2.dart

@@ -11,7 +11,6 @@ class HeroService {
 
   //#docregion ctor
   HeroService(this._logger);
-
   //#enddocregion ctor
   List<Hero> getHeroes() {
     _logger.log('Getting heroes ...');

public/docs/_examples/dependency-injection/dart/lib/heroes/hero_service_provider.dart

@@ -6,8 +6,7 @@ import '../user_service.dart';
 import 'hero_service.dart';
 
 // #docregion factory
-@Injectable()
-heroServiceFactory(Logger logger, UserService userService) =>
+HeroService heroServiceFactory(Logger logger, UserService userService) =>
     new HeroService(logger, userService.user.isAuthorized);
 // #enddocregion factory