docs(dependency injection): minor tweaks

closes #755

public/docs/_examples/dependency-injection/ts/app/heroes/hero.service.2.ts

@@ -7,7 +7,9 @@ import {Logger}     from '../logger.service';
 @Injectable()
 export class HeroService {
 
+  //#docregion ctor
   constructor(private _logger: Logger) {  }
+  //#enddocregion ctor
 
   getHeroes() {
     this._logger.log('Getting heroes ...')

public/docs/_examples/dependency-injection/ts/app/providers.component.ts

@@ -1,4 +1,5 @@
 // Examples of provider arrays
+//#docplaster
 import { Component, Host, Inject, Injectable,
          provide, Provider}    from 'angular2/core';
 
@@ -103,10 +104,8 @@ class EvenBetterLogger {
   template: template,
   providers:
     //#docregion providers-5
-    [
+    [ UserService,
-      UserService,
+      provide(Logger, {useClass: EvenBetterLogger}) ]
-      provide(Logger, {useClass: EvenBetterLogger})
-    ]
     //#enddocregion providers-5
 })
 export class ProviderComponent5 {
@@ -131,11 +130,9 @@ class OldLogger {
   template: template,
   providers:
     //#docregion providers-6a
-    [
+    [ NewLogger,
-      NewLogger,
       // Not aliased! Creates two instances of `NewLogger`
-      provide(OldLogger, {useClass:NewLogger})
+      provide(OldLogger, {useClass:NewLogger}) ]
-    ]
     //#enddocregion providers-6a
 })
 export class ProviderComponent6a {
@@ -156,11 +153,9 @@ export class ProviderComponent6a {
   template: template,
   providers:
     //#docregion providers-6b
-    [
+    [ NewLogger,
-      NewLogger,
       // Alias OldLogger w/ reference to NewLogger
-      provide(OldLogger, {useExisting: NewLogger})
+      provide(OldLogger, {useExisting: NewLogger}) ]
-    ]
     //#enddocregion providers-6b
 })
 export class ProviderComponent6b {
@@ -306,7 +301,9 @@ export class ProviderComponent10b {
         log: (msg:string)=> this._logger.logs.push(msg),
         logs: []
       }
+    // #enddocregion provider-10-logger      
       this._logger.log("Optional logger was not available.")
+    // #docregion provider-10-logger      
     }
     // #enddocregion provider-10-logger
     else {

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

@@ -399,38 +399,41 @@ include ../../../../_includes/_util-fns
   We're likely to need the same logger service everywhere in our application 
   so we put it at the root level of the application in the `app/` folder and
   we register it in the `providers` array of the metadata for our application root component, `AppComponent`.
-+makeExample('dependency-injection/ts/app/providers.component.ts','providers-1', 'app/app.component.ts (providers)')
++makeExample('dependency-injection/ts/app/providers.component.ts','providers-logger', 'app/app.component.ts (providers)')
 :marked
-  If we forget to register it, Angular will throw an exception when it first needs the logger:
+  If we forget to register it, Angular throws an exception when it first looks for the logger:
 code-example(format).
   EXCEPTION: No provider for Logger! (HeroListComponent -> HeroService -> Logger)
 :marked
-  That's telling us that the dependency injector couldn't find the *provider* for the logger
+  That's Angular telling us that the dependency injector couldn't find the *provider* for the logger.
-  when it first tried to call the logger — inside the `HeroService` when the `HeroListComponent`
+  It needed that provider to create a `Logger` to inject into a new `HeroService` which it needed to
-  was calling for heroes.
+  create and inject into a new `HeroListComponent`. 
-  The *provider* is the subject of our next section.
+  
+  The chain of creations started with the `Logger` provider. The *provider* is the subject of our next section.
   
   But wait!  What if the logger is optional?
   <a id="optional"></a>
   ### Optional dependencies
   
   Our `HeroService` currently requires a `Logger`. What if we could get by without a logger?
-  We'd use it if we had it, ignore it if we didn't.
+  We'd use it if we had it, ignore it if we didn't. We can do that.
   
-  First we import the `@Optional` decorator.
+  First import the `@Optional()` decorator.
 +makeExample('dependency-injection/ts/app/providers.component.ts','import-optional')(format='.')
 :marked
-  Then rewrite the constructor with that decorator to make the logger optional.
+  Then rewrite the constructor with `@Optional()` decorator preceding the private `_logger` parameter.
+  That tells the injector that `_logger` is optional.
 +makeExample('dependency-injection/ts/app/providers.component.ts','provider-10-ctor')(format='.')
 :marked
   Be prepared for a null logger. If we don't register one somewhere up the line,
-  the injector will inject `null`. We have a method that logs. What can we do?
+  the injector will inject `null`. We have a method that logs. 
+  What can we do to avoid a null reference exception?
   
-  We could substitute a *do-nothing* logger stub so that our methods continue to work:
+  We could substitute a *do-nothing* logger stub so that calling methods continue to work:
 +makeExample('dependency-injection/ts/app/providers.component.ts','provider-10-logger')(format='.')
 :marked
   Obviously we'd take a more sophisticated approach if the logger were optional
-  elsewhere as well. 
+  in multiple locations. 
   
   But enough about optional loggers. In our sample application, the `Logger` is required. 
   We must register a `Logger` with the application injector using *providers*
@@ -445,18 +448,15 @@ code-example(format).
   The injector relies on **providers** to create instances of the services 
   that it injects into components and other services.
 
-  We must register *providers* with the injector or it won't know what to do. 
+  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:
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-logger')
 :marked
-  The `providers` array appears to hold service classes (one service class in this example). 
+  The `providers` array appears to hold a service class. 
-  In reality it holds instances of the [Provider](../api/core/Provider-class.html) class.
+  In reality it holds an instance the [Provider](../api/core/Provider-class.html) class that can create that service.
-  
+ 
-  In our example, when the `HeroService` constructor specifies `logger:Logger`, it's expecting
+  There are many ways to *provide* something that looks and behaves like a `Logger`.
-  something that has the shape and behavior of the `Logger` class.
-  
-  There are many ways to *provide* something that has the shape and behavior of a `Logger`.
   The `Logger` class itself is an obvious and natural provider - it has the right shape and it's designed to be created. 
   But it's not the only way.
   
@@ -511,7 +511,7 @@ code-example(format).
   ### Aliased Class Providers
 
   Suppose there is an old component that depends upon an `OldLogger` class.
-  `OldLogger` has the same interface as the `NewLogger` but, for some reason,
+  `OldLogger` has the same interface as the `NewLogger` but for some reason
   we can't update the old component to use it.
 
   When the *old* component logs a message with `OldLogger`, 
@@ -545,14 +545,15 @@ code-example(format).
 
   Sometimes we need to create the dependent value dynamically, 
   based on information we won't have until the last possible moment.
-  Maybe the information can change.
+  Maybe the information keeps changes repeatedly in the course of the browser session..
   
   Suppose also that the injectable service has no independent access to the source of this information.
   
-  This situation calls for a **factory provider** as we illustrate next.
+  This situation calls for a **factory provider**.
   
-  Our HeroService should hide *secret* heroes from normal users. 
+  Let's illustrate by adding a new business requirement:
-  Only authorized users should see them.
+  the HeroService must hide *secret* heroes from normal users. 
+  Only authorized users should see secret heroes.
   
   Like the `EvenBetterLogger`, the `HeroService` needs a fact about the user. 
   It needs to know if the user is authorized to see secret heroes.
@@ -560,6 +561,8 @@ code-example(format).
   as when we log in a different user.
   
   Unlike `EvenBetterLogger`, we can't inject the `UserService` into the `HeroService`.
+  The `HeroService` won't have direct access to the user information to decide
+  who is authoriazed and who is not.
 .l-sub-section
   :marked
     Why? We don't know either. Stuff like this happens.
@@ -573,9 +576,9 @@ code-example(format).
   A factory provider needs a factory function:
 +makeExample('dependency-injection/ts/app/heroes/hero.service.provider.ts','factory', 'app/heroes/hero.service.provider.ts (factory)')(format='.')
 :marked
-  Although our `HeroService` knows nothing about the `UserService`, our factory function does.
+  Although the `HeroService` has no access to the `UserService`, our factory function does.
   
-  We inject both the `Logger` and the `UserService` into the factory provider:
+  We inject both the `Logger` and the `UserService` into the factory provider and let the injector pass them along to the factory function:
 +makeExample('dependency-injection/ts/app/heroes/hero.service.provider.ts','provider', 'app/heroes/hero.service.provider.ts (provider)')(format='.')
 :marked
 
@@ -586,12 +589,15 @@ code-example(format).
 
     The `deps` property is an array of [provider tokens](#token).
     The `Logger` and `UserService` classes serve as tokens for their own class providers.
+    The injector resolves these tokens and injects the corresponding services into the matching factory function parameters.
 :marked
-  Notice that we've captured the factory provider in an exported variable, `heroServiceProvider`.
+  Notice that we captured the factory provider in an exported variable, `heroServiceProvider`.
-  This extra step makes it easier for us to register our `HeroService` whereever we need it.
+  This extra step makes the factory provider re-usable. 
+  We can register our `HeroService` with this variable whereever we need it.
   
   In our sample, we need it only in the `HeroesComponent` 
-  where it replaces the previous `HeroService` registration in the metadata `providers` array:
+  where it replaces the previous `HeroService` registration in the metadata `providers` array.
+  Here we see the new and the old implementation side-by-side:
 +makeTabs(
   `dependency-injection/ts/app/heroes/heroes.component.ts, 
   dependency-injection/ts/app/heroes/heroes.component.1.ts`,
@@ -606,11 +612,11 @@ code-example(format).
 
   When we register a provider with an injector we associate that provider with a dependency injection token.
   The injector maintains an internal *token/provider* map that it references when
-  asked for a dependency
+  asked for a dependency. The token is the key to the map.
   
   In all previous examples, the dependency value has been a class *instance* and 
-  the class *type* served as its own lookup token.
+  the class *type* served as its own lookup key.
-  Here we get a `HeroService` directly from the injector by supplying the `HeroService` type as the token.
+  Here we get a `HeroService` directly from the injector by supplying the `HeroService` type as the key/token.
 +makeExample('dependency-injection/ts/app/injector.component.ts','get-hero-service')(format='.')
 :marked
   We have similar good fortune (in typescript) when we write a constructor that requires an injected class-based dependency.
@@ -618,7 +624,7 @@ code-example(format).
   service associated with that `HeroService` class token:
 +makeExample('dependency-injection/ts/app/providers.component.ts','provider-8-ctor')(format=".")
 :marked
-  This is all especially convenient when we consider that most dependency values are provided by classes.
+  This is especially convenient when we consider that most dependency values are provided by classes.
   
   ### Non-class Dependencies
   
@@ -626,7 +632,7 @@ code-example(format).
   Sometimes the thing we want to inject is a string, a function, or an object.
 
   Applications often define configuration objects with lots of small facts like the title of the application or the address of a web api endpoint.
-  These configuration objects aren't always instances of a class. They're just objects ... like this one:
+  These configuration objects aren't always instances of a class. They tend to be object hashes like this one:
 
 +makeExample('dependency-injection/ts/app/app.config.ts','config','app/app-config.ts')(format='.')
 :marked
@@ -638,13 +644,19 @@ code-example(format).
 // begin Typescript only
 <a id="interface"></a>
 :marked
+  ### Interfaces aren't valid tokens
+
   The `CONFIG` constant has an interface, `Config`. Unfortunately, we
-  **cannot use an interface as a token**
+  cannot use an interface as a token:
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-9a-interface')(format=".")
 +makeExample('dependency-injection/ts/app/providers.component.ts','provider-9a-ctor-interface')(format=".")
 :marked
-  It's not Angular's fault. An interface is a TypeScript design-time artifact. 
+  That seems strange if we're used to dependency injection in strongly-typed languages where
-  It disappears from the generated JavaScript so there is no interface type information for Angular to find at runtime.
+  an interface is the preferred dependency lookup key.
+  
+  It's not Angular's fault. An interface is a TypeScript design-time artifact. JavaScript doesn't have interfaces.
+  The TypeScript interface disappears from the generated JavaScript. 
+  There is no interface type information left for Angular to find at runtime.
 // end Typescript only
 <a id="string-token"></a>
 :marked
@@ -684,7 +696,9 @@ code-example(format).
 
 .l-sub-section
   :marked
-    Angular uses `OpaqueTokens` to register all of its non-class dependencies.
+    Angular itself uses `OpaqueTokens` to register all of its own non-class dependencies. For example,
+    [HTTP_PROVIDERS](https://angular.io/docs/ts/latest/api/http/HTTP_PROVIDERS-let.html)
+    is the `OpaqueToken` associated with an array of providers for persisting data with the Angular `Http` client.
     
     Internally, the `Provider` turns both the string and the class type into an `OpaqueToken`
     and keys its *token/provider* map with that.
@@ -709,8 +723,13 @@ code-example(format).
 +makeExample('dependency-injection/ts/app/injector.component.ts', 'injector',
              'app/injector.component.ts')
 :marked
-  Angular injects the component's own `Injector` which the component uses to acquire services.
+  The `Injector` is itself an injectable service.
-  The services themselves are not injected. They're retrieved via the injector.
+  
+  In this example, Angular injects the component's own `Injector` into the component's constructor.
+  The component then asks the injected injector for the services it wants.
+  
+  Note that the services themselves are not injected into the component.
+  They are retrieved by calling `injector.get`.
   
   The `get` method throws an error if it can't resolve the requested service.
   We can call `getOptional` instead, which we do in one case
@@ -718,14 +737,15 @@ code-example(format).
   
 .l-sub-section
   :marked
-    This technique is an example of the [Service Locator Pattern](https://en.wikipedia.org/wiki/Service_locator_pattern).
+    The technique we just described is an example of the 
+    [Service Locator Pattern](https://en.wikipedia.org/wiki/Service_locator_pattern).
     
     We **avoid** this technique unless we genuinely need it.
     It encourages a careless grab-bag approach such as we see here.
     It's difficult to explain, understand, and test.
     We can't know by inspecting the constructor what this class requires or what it will do.
-    It could acquire services from any ancestor component, not just its own.    
+    It could acquire services from any ancestor component, not just its own. 
-    We're forced to spelunk the implementation and hope for the best.
+    We're forced to spelunk the implementation to discover what it does.
     
     Framework developers may take this approach when they 
     must acquire services generically and dynamically.