docs(dependency-injection): updates to match TS; also minor TS fixes (#2875)

* cache file sync before making updates to Dart jade

* app.module.ts: fix ngmodule docregion

* [TS] dependency-injection.jade updates

* [Dart] dependency-injection.jade updates

* final ts/_cache file sync

public/docs/_examples/dependency-injection/ts/app/app.module.ts

@@ -32,6 +32,7 @@ import {
     AppComponent,
     CarComponent,
     HeroesComponent,
+    // #enddocregion ngmodule
     HeroListComponent,
     InjectorComponent,
     TestComponent,
@@ -46,6 +47,7 @@ import {
     Provider8Component,
     Provider9Component,
     Provider10Component,
+    // #docregion ngmodule
   ],
   // #docregion ngmodule-providers
   providers: [
@@ -56,4 +58,3 @@ import {
   bootstrap: [ AppComponent ]
 })
 export class AppModule { }
-// #enddocregion ngmodule

public/docs/dart/latest/guide/dependency-injection.jade

@@ -10,6 +10,34 @@ block ctor-syntax
       We also leveraged Dart's constructor syntax for declaring parameters and
       initializing properties simultaneously.
 
+block register-provider-ngmodule
+  :marked
+    Before we do, let's see an example of provider registration during bootstrapping:
+
+  +makeExcerpt('app/main.1.ts (discouraged)', 'bootstrap-discouraged', '')
+
+  :marked
+    The injector now knows about our `HeroService`.
+    An instance of our `HeroService` will be available for injection across our entire application.
+
+    Of course we can't help wondering about that comment telling us not to do it this way.
+    It *will* work. It's just not a best practice.
+    The bootstrap provider option is intended for configuring and overriding Angular's own
+    preregistered services, such as its routing support.
+
+    The preferred approach is to register application providers in application components.
+    Because the `HeroService` is used within the *Heroes* feature area —
+    and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`.
+
+block ngmodule-vs-component
+  :marked
+    Look at the `providers` part of the `@Component` annotation.
+    An instance of the `HeroService` is now available for injection in this `HeroesComponent`
+    and all of its child components.
+
+    The `HeroesComponent` itself doesn't happen to need the `HeroService`.
+    But its child `HeroListComponent` does, so we head there next.
+
 block injectable-not-always-needed-in-ts
   //- The [Angular Dart Transformer](https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer)
   //- generates static code to replace the use of dart:mirrors. It requires that types be

public/docs/ts/_cache/guide/dependency-injection.jade

@@ -247,43 +247,49 @@ block ctor-syntax
   We don't have to create an Angular injector.
   Angular creates an application-wide injector for us during the bootstrap process.
 
-+makeExample('dependency-injection/ts/app/main.ts', 'bootstrap', 'app/main.ts (excerpt)')(format='.')
++makeExcerpt('app/main.ts', 'bootstrap')
 
 :marked
   We do have to configure the injector by registering the **providers**
   that create the services our application requires.
   We'll explain what [providers](#providers) are later in this chapter.
-  Before we do, let's see an example of provider registration during bootstrapping:
 
-+makeExample('dependency-injection/ts/app/main.1.ts', 'bootstrap-discouraged')(format='.')
+block register-provider-ngmodule
+  :marked
+    We can either register a provider within an [NgModule](ngmodule.html) or in application components
 
-:marked
+    ### Registering providers in an NgModule
-  The injector now knows about our `HeroService`.
+    Here's our AppModule where we register a `Logger`, a `UserService`, and an `APP_CONFIG` provider.
-  An instance of our `HeroService` will be available for injection across our entire application.
 
-  Of course we can't help wondering about that comment telling us not to do it this way.
+  - var app_module_ts = 'app/app.module.ts';
-  It *will* work. It's just not a best practice.
+  +makeExcerpt(app_module_ts + ' (excerpt)', 'ngmodule', app_module_ts, { otl: /(providers:)/ })
-  The bootstrap provider option is intended for configuring and overriding Angular's own
+  //- The preferred approach is to register application providers in application components.
-  preregistered services, such as its routing support.
+  //- Because the `HeroService` is used within the *Heroes* feature area —
-
+  //- and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`.
-  The preferred approach is to register application providers in application components.
-  Because the `HeroService` is used within the *Heroes* feature area —
-  and nowhere else — the ideal place to register it is in the top-level `HeroesComponent`.
 
 :marked
   ### Registering providers in a component
+
   Here's a revised `HeroesComponent` that registers the `HeroService`.
 
-- var stylePattern = { otl: /(providers:.*),/ };
+- var stylePattern = { otl: /(providers:[^,]+),/ };
-+makeExample('dependency-injection/ts/app/heroes/heroes.component.1.ts', 'full','app/heroes/heroes.component.ts', stylePattern)(format='.')
++makeExample('app/heroes/heroes.component.1.ts', 'full', 'app/heroes/heroes.component.ts', stylePattern)(format='.')
 
-:marked
+block ngmodule-vs-component
-  Look closely at the `providers` part of the `@Component` metadata.
+  :marked
-  An instance of the `HeroService` is now available for injection in this `HeroesComponent`
+    ### When to use the NgModule and when an application component?
-  and all of its child components.
 
-  The `HeroesComponent` itself doesn't happen to need the `HeroService`.
+    On the one hand, a provider in an NgModule is registered in the root injector. That means that every provider
-  But its child `HeroListComponent` does, so we head there next.
+    registered within an NgModule will be accessible in the _entire application_.
+
+    On the other hand, a provider registered in an application component is available only on that component and all its children.
+
+    We want the `APP_CONFIG` service to be available all across the application, but a `HeroService` is only used within the *Heroes*
+    feature area and nowhere else.
+
+  .l-sub-section
+    :marked
+     Also see *"Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module).
 
 :marked
   ### Preparing the HeroListComponent for injection
@@ -387,7 +393,6 @@ block ctor-syntax
   The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `#{_priv}logger`.
   We call that property within our `getHeroes` method when anyone asks for heroes.
 
-//- FIXME refer to Dart API when that page becomes available.
 - var injUrl = '../api/core/index/Injectable-decorator.html';
 h3#injectable Why @Injectable()?
 :marked
@@ -462,7 +467,7 @@ block injectable-not-always-needed-in-ts
 
   Our logger service is quite simple:
 
-+makeExample('dependency-injection/ts/app/logger.service.ts', null, 'app/logger.service.ts')
++makeExample('app/logger.service.ts')
 
 block real-logger
   //- N/A
@@ -470,9 +475,9 @@ block real-logger
 :marked
   We're likely to need the same logger service everywhere in our application,
   so we put it in the project's `#{_appDir}` folder, and
-  we register it in the `providers` #{_array} of the metadata for our application root component, `AppComponent`.
+  we register it in the `providers` #{_array} of our application !{_moduleVsComp}, `!{_AppModuleVsAppComp}`.
 
-+makeExcerpt('app/providers.component.ts','providers-logger','app/app.component.ts (excerpt)')
++makeExcerpt('app/providers.component.ts (excerpt)', 'providers-logger','app/app.module.ts')
 
 :marked
   If we forget to register the logger, Angular throws an exception when it first looks for the logger:
@@ -497,7 +502,7 @@ code-example(format="nocode").
 
   We must register a service *provider* with the injector, or it won't know how to create the service.
 
-  Earlier we registered the `Logger` service in the `providers` #{_array} of the metadata for the `AppComponent` like this:
+  Earlier we registered the `Logger` service in the `providers` #{_array} of the metadata for the `AppModule` like this:
 
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-logger')
 
@@ -766,7 +771,7 @@ block what-should-we-use-as-token
       The TypeScript interface disappears from the generated JavaScript.
       There is no interface type information left for Angular to find at runtime.
 
-//- FIXME simplify once APIs are defined for Dart.
+//- FIXME update once https://github.com/dart-lang/angular2/issues/16 is addressed.
 - var opaquetoken = _docsFor == 'dart' ? '<b>OpaqueToken</b>' : '<a href="../api/core/index/OpaqueToken-class.html"><b>OpaqueToken</b></a>'
 :marked
   ### OpaqueToken
@@ -796,9 +801,9 @@ block what-should-we-use-as-token
 
 block dart-map-alternative
   :marked
-    Or we can provide and inject the configuration object in our top-level `AppComponent`.
+    Or we can provide and inject the configuration object in an ngModule like `AppModule`.
 
-  +makeExcerpt('app/app.component.ts','providers')
+  +makeExcerpt('app/app.module.ts','ngmodule-providers')
 
 #optional
 :marked

public/docs/ts/latest/guide/dependency-injection.jade

@@ -247,43 +247,49 @@ block ctor-syntax
   We don't have to create an Angular injector.
   Angular creates an application-wide injector for us during the bootstrap process.
 
-+makeExample('dependency-injection/ts/app/main.ts', 'bootstrap', 'app/main.ts (excerpt)')(format='.')
++makeExcerpt('app/main.ts', 'bootstrap')
 
 :marked
   We do have to configure the injector by registering the **providers**
   that create the services our application requires.
   We'll explain what [providers](#providers) are later in this chapter.
 
+block register-provider-ngmodule
+  :marked
     We can either register a provider within an [NgModule](ngmodule.html) or in application components
 
     ### Registering providers in an NgModule
     Here's our AppModule where we register a `Logger`, a `UserService`, and an `APP_CONFIG` provider.
 
-- var stylePattern = { otl: /(providers)/ };
+  - var app_module_ts = 'app/app.module.ts';
-+makeExample('dependency-injection/ts/app/app.module.ts', 'ngmodule','app/app.module.ts', stylePattern)(format='.')
+  +makeExcerpt(app_module_ts + ' (excerpt)', 'ngmodule', app_module_ts, { otl: /(providers:)/ })
-  <!--The preferred approach is to register application providers in application components.
+  //- The preferred approach is to register application providers in application components.
-  Because the `HeroService` is used within the *Heroes* feature area &mdash;
+  //- Because the `HeroService` is used within the *Heroes* feature area &mdash;
-  and nowhere else &mdash; the ideal place to register it is in the top-level `HeroesComponent`.-->
+  //- and nowhere else &mdash; the ideal place to register it is in the top-level `HeroesComponent`.
 
 :marked
   ### Registering providers in a component
+
   Here's a revised `HeroesComponent` that registers the `HeroService`.
 
-+makeExample('dependency-injection/ts/app/heroes/heroes.component.1.ts', 'full','app/heroes/heroes.component.ts', stylePattern)(format='.')
+- var stylePattern = { otl: /(providers:[^,]+),/ };
++makeExample('app/heroes/heroes.component.1.ts', 'full', 'app/heroes/heroes.component.ts', stylePattern)(format='.')
 
-:marked
+block ngmodule-vs-component
+  :marked
     ### When to use the NgModule and when an application component?
+
     On the one hand, a provider in an NgModule is registered in the root injector. That means that every provider
-  registered within an NgModule will be accessible in the entire application.
+    registered within an NgModule will be accessible in the _entire application_.
 
     On the other hand, a provider registered in an application component is available only on that component and all its children.
 
     We want the `APP_CONFIG` service to be available all across the application, but a `HeroService` is only used within the *Heroes*
-  feature area &mdash; and nowhere else. &mdash;
+    feature area and nowhere else.
 
-.l-sub-section
+  .l-sub-section
     :marked
-    Read also **Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?** in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module) chapter.
+     Also see *"Should I add app-wide providers to the root `AppModule` or the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#root-component-or-module).
 
 :marked
   ### Preparing the HeroListComponent for injection
@@ -387,7 +393,6 @@ block ctor-syntax
   The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `#{_priv}logger`.
   We call that property within our `getHeroes` method when anyone asks for heroes.
 
-//- FIXME refer to Dart API when that page becomes available.
 - var injUrl = '../api/core/index/Injectable-decorator.html';
 h3#injectable Why @Injectable()?
 :marked
@@ -462,7 +467,7 @@ block injectable-not-always-needed-in-ts
 
   Our logger service is quite simple:
 
-+makeExample('dependency-injection/ts/app/logger.service.ts', null, 'app/logger.service.ts')
++makeExample('app/logger.service.ts')
 
 block real-logger
   //- N/A
@@ -470,9 +475,9 @@ block real-logger
 :marked
   We're likely to need the same logger service everywhere in our application,
   so we put it in the project's `#{_appDir}` folder, and
-  we register it in the `providers` #{_array} of the metadata for our application module, `AppModule`.
+  we register it in the `providers` #{_array} of our application !{_moduleVsComp}, `!{_AppModuleVsAppComp}`.
 
-+makeExcerpt('app/providers.component.ts','providers-logger','app/app.module.ts (excerpt)')
++makeExcerpt('app/providers.component.ts (excerpt)', 'providers-logger','app/app.module.ts')
 
 :marked
   If we forget to register the logger, Angular throws an exception when it first looks for the logger:
@@ -766,7 +771,7 @@ block what-should-we-use-as-token
       The TypeScript interface disappears from the generated JavaScript.
       There is no interface type information left for Angular to find at runtime.
 
-//- FIXME simplify once APIs are defined for Dart.
+//- FIXME update once https://github.com/dart-lang/angular2/issues/16 is addressed.
 - var opaquetoken = _docsFor == 'dart' ? '<b>OpaqueToken</b>' : '<a href="../api/core/index/OpaqueToken-class.html"><b>OpaqueToken</b></a>'
 :marked
   ### OpaqueToken