post-review updates

Author: chalin

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

@@ -1,15 +1,10 @@
-// #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';
@@ -62,6 +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. ';
 }

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

@@ -4,7 +4,6 @@ import 'package:angular2/core.dart';
 @Injectable()
 class Logger {
   List<String> _logs = [];
-
   List<String> get logs => _logs;
 
   void log(String message) {

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

@@ -95,8 +95,10 @@ block config-obj-maps
 
 block what-should-we-use-as-token
   :marked
-    But what should we use as the token?
-    We could use the **[Map][]** interface.
+    But what should we use as the token? 
+    While we _could_ use **[Map][]**, we _should not_ because (like
+    `String`) `Map` is too general. Our app might depend on several maps, each
+    for a different purpose.
 
     [Map]: https://api.dartlang.org/stable/dart-core/Map-class.html
 
@@ -107,32 +109,32 @@ block what-should-we-use-as-token
       Dart doesn't have this limitation;
       every class implicitly defines an interface,
       so interface names are just class names.
-
-  :marked
-    The problem with using `Map` as a token, is not that it is an abstract
-    class, but rather that it is very general purpose (like `String`) and so
-    our application may depend on several maps each used for a
-    different purpose.
+      `Map` is a *valid* token even though it's the name of an abstract class;
+      it's just *unsuitable* as a token because it's too general.
 
 block dart-map-alternative
   :marked
     As an alternative to using a configuration `Map`, we can define
-    a custom class type:
+    a custom configuration class:
 
   +makeExample('dependency-injection/ts/app/app.config.ts','config-alt','app/app-config.ts (alternative config)')(format='.')
 
   :marked
-    One of the key benefits of defining a configuration object class, is
-    strong static checking relative to configuration property names and their types.
-    The Dart [cascade operator][cascade-op] provides a convenient means of initializing
-    the configuration object. Use of the cascaded object initialization idiom
+    Defining a configuration class has a few benefits. One key benefit
+    is strong static checking: we'll be warned early if we misspell a property
+    name or assign it a value of the wrong type.
+    The Dart [cascade notation][cascade] (`..`) provides a convenient means of initializing
+    a configuration object. 
+
+    Use of the cascaded initialization idiom
     prevents us from defining our configuration object instance as `const`. 
-    As a consequencem we cannot declare a [value provider](#value-provider),
-    but a [factory provider](#factory-provider) does the trick — as
-    we illustrate by providing and injecting the configuration object in our
+    As a consequence, we cannot declare a [value provider](#value-provider),
+    but a [factory provider](#factory-provider) does the trick.
+
+    We illustrate this below by providing and injecting the configuration object in our
     top-level `AppComponent`:
 
-    [cascade-op]: https://www.dartlang.org/docs/dart-up-and-running/ch02.html#cascade
+    [cascade]: https://www.dartlang.org/docs/dart-up-and-running/ch02.html#cascade
 
   +makeExcerpt('lib/app_component.dart','providers')
   +makeExcerpt('lib/app_component.dart','ctor')

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

@@ -34,7 +34,7 @@ p Run the #[+liveExampleLink2()].
 
   Our `Car` needs an engine and tires. Instead of asking for them,
   the `Car` constructor instantiates its own copies from
-  the very specific classes, `Engine` and `Tires`.
+  the very specific classes `Engine` and `Tires`.
 
   What if the `Engine` class evolves and its constructor requires a parameter?
   Our `Car` is broken and stays broken until we rewrite it along the lines of
@@ -422,9 +422,9 @@ block injectable-not-always-needed-in-ts
 
   We *can* add it if we really want to. It isn't necessary because the
   `HeroesComponent` is already marked with `@Component`, and this
-  !{_decorator} class (like `@Directive` and `@Pipe` which we will study later
-  on) is a subtype of <a href="#{injMetaUrl}">InjectableMetadata</a>.  It is in
-  fact <a href="#{injMetaUrl}">InjectableMetadata</a> #{_decorator}s that
+  !{_decorator} class (like `@Directive` and `@Pipe`, which we'll learn about later)
+  is a subtype of <a href="#{injMetaUrl}">InjectableMetadata</a>.  It is in
+  fact `InjectableMetadata` #{_decorator}s that
   identify a class as a target for instantiation by an injector.
 
 block ts-any-decorator-will-do
@@ -701,7 +701,7 @@ block dart-diff-const-metadata-ctor
 +makeTabs(
   `dependency-injection/ts/app/heroes/heroes.component.ts,
   dependency-injection/ts/app/heroes/heroes.component.1.ts`,
-  null,
+  ',full',
   `app/heroes/heroes.component (v3),
   app/heroes/heroes.component (v2)`,
   stylePattern)
@@ -779,7 +779,8 @@ block what-should-we-use-as-token
 :marked
   ### OpaqueToken
 
-  The solution is to define and use an !{opaquetoken}.
+  One solution to choosing a provider token for non-class dependencies is
+  to define and use an !{opaquetoken}.
   The definition looks like this:
 
 +makeExample('dependency-injection/ts/app/app.config.ts','token')(format='.')
@@ -798,8 +799,8 @@ block what-should-we-use-as-token
 - var configType = _docsFor == 'dart' ? '<code>Map</code>' : '<code>AppConfig</code>'
 .l-sub-section
   :marked
-    Although it plays no role in dependency injection,
-    the !{configType} interface supports typing of the configuration object within the class.
+    Although the !{configType} interface plays no role in dependency injection,
+    it supports typing of the configuration object within the class.
 
 block dart-map-alternative
   :marked
@@ -813,16 +814,17 @@ block dart-map-alternative
 
   Our `HeroService` *requires* a `Logger`, but what if it could get by without
   a logger?
-  As is illustrated next, we can indicate that to the dependency injection
-  framework by marking the constructor's argument as optional.
+  We can tell Angular that the dependency is optional by annotating the 
+  constructor argument with `@Optional()`:
 
 +ifDocsFor('ts')
   +makeExample('dependency-injection/ts/app/providers.component.ts','import-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`.
+  When using `@Optional()`, our code must be prepared for a null value. If we
+  don't register a logger somewhere up the line, the injector will set the
+  value of `logger` to null.
 
 .l-main-section
 :marked