incorporate more comments from thso

Author: kwalrath

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

@@ -1,3 +1,4 @@
+// #docplaster
 // Examples with car and engine variations
 import 'car.dart';
 
@@ -18,6 +19,8 @@ class Engine2 implements Engine {
 
   Engine2(this.cylinders);
 }
+
+// Later, where the car is created...
 //#enddocregion car-ctor-instantiation-with-param
 
 Car superCar() {
@@ -39,6 +42,8 @@ class MockEngine extends Engine {
 class MockTires extends Tires {
   String make = 'YokoGoodStone';
 }
+
+// Later, where the car is created for testing...
 //#enddocregion car-ctor-instantiation-with-mocks
 Car testCar() {
   //#docregion car-ctor-instantiation-with-mocks

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

@@ -160,6 +160,10 @@ include ../_util-fns
 :marked
   We supply two arguments to the `Provider` constructor.
 +includeShared('{ts}', 'providers-provide-4-2')
+:marked
+  The second is a named parameter, such as `useClass`,
+  that we can think of as a *recipe* for creating the dependency value.
+  There are many ways to create dependency values... and many ways to write a recipe.
 +includeShared('{ts}', 'providers-alternative-1')
 +makeExample('dependency-injection/dart/lib/providers_component.dart','providers-4')
 .callout.is-helpful
@@ -212,9 +216,7 @@ p <b>[PENDING: How about a better name than ProviderComponent8?]</b>
 +includeShared('{ts}', 'tokens-non-class-deps-1')
 p <b>[PENDING: What's the Dart equivalent of "object hash"? How can we shorten/improve this code?]</b>
 +makeExample('dependency-injection/dart/lib/app_config.dart','config','lib/app_config.dart (excerpt)')(format='.')
-+includeShared('{ts}', 'tokens-non-class-deps-2')
-p <b>[PENDING: That's not right. That text is from the TypeScript version. How should the Dart code/text be different?]</b>
-p <b>[PENDING: TypeScript has a whole section here on "Interfaces aren't valid tokens". But they are in Dart!]</b>
+p <b>[PENDING: add explanatory/transition text here]</b>
 .callout.is-helpful
   header Dart difference: Interfaces are valid tokens
   :marked
@@ -226,7 +228,7 @@ p <b>[PENDING: TypeScript has a whole section here on "Interfaces aren't valid t
     (usually, that's the name of an abstract class)
     as the first argument.
 +includeShared('{ts}', 'tokens-string-1')
-p <b>[PENDING: Where did CONFIG_HASH come from? (lib/app_config.dart) Why does the code use that instead of CONFIG? (only matters if we keep the code, I suppose)]</b>
+p <b>[PENDING: Why is that "fortunate"? String tokens seem UNfortunate... Also, where did CONFIG_HASH come from? (lib/app_config.dart) Why does the code use that instead of CONFIG? (only matters if we keep the code, I suppose)]</b>
 +makeExample('dependency-injection/dart/lib/providers_component.dart','providers-9a')(format=".")
 +includeShared('{ts}', 'tokens-string-2')
 p <b>[PENDING: I don't like showing ProviderComponent9a. Also... can we make this code easier to read?]</b>

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

@@ -61,7 +61,7 @@ include ../_util-fns
   if we can't swap in low-pressure tires during the test?
 
   We have no control over the car's hidden dependencies.
-  When we can't control the dependencies, a class become difficult to test.
+  When we can't control the dependencies, a class becomes difficult to test.
 
   How can we make `Car` more robust, flexible, and testable?
 
@@ -196,17 +196,11 @@ include ../_util-fns
   It governs all the child components of this area.
   Our stripped down version has only one child, `HeroListComponent`,
   which displays a list of heroes.
-
-.l-sub-section
-  :marked
-    Do we really need so many files? Of course not!
-    We're going *beyond* the strictly necessary
-    in order to illustrate patterns that work well in real applications.
 // #enddocregion di-2
 // #docregion di-3
 :marked
   Right now `HeroListComponent` gets heroes from `HEROES`, an in-memory collection
-  defined in another file and imported by this component.
+  defined in another file.
   That may suffice in the early stages of development, but it's far from ideal.
   As soon as we try to test this component or want to get our heroes data from a remote server,
   we'll have to change the implementation of `heroes` and
@@ -531,7 +525,8 @@ code-example(format, language="html").
 // #docregion providers-2
 - var lang = current.path[1]
 - var implements = lang == 'dart' ? 'implements' : 'looks and behaves like a '
- #{decoration}
+- var objectlike = lang == 'dart' ? '' : 'an object that behaves like '
+- var loggerlike = lang == 'dart' ? '' : 'We could provide a logger-like object. '
 :marked
   The `providers` array appears to hold a service class.
   In reality it holds an instance of the [Provider](/docs/ts/latest/api/core/Provider-class.html) class that can create that service.
@@ -540,8 +535,8 @@ code-example(format, language="html").
   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.
 
-  We can configure the injector with alternative providers that can deliver an object that behaves like a `Logger`.
-  We could provide a substitute class. We could provide a logger-like object.
+  We can configure the injector with alternative providers that can deliver #{objectlike} a `Logger`.
+  We could provide a substitute class. #{loggerlike}
   We could give it a provider that calls a logger factory function.
   Any of these approaches might be a good choice under the right circumstances.
 
@@ -582,11 +577,13 @@ code-example(format, language="html").
 :marked
   The first is the [token](#token) that serves as the key for both locating a dependency value
   and registering the provider.
+// #enddocregion providers-provide-4-2
 
+// Dart is different here (uses an optional parameter)
+:marked
   The second is a provider definition object,
   which we can think of as a *recipe* for creating the dependency value.
   There are many ways to create dependency values... and many ways to write a recipe.
-// #enddocregion providers-provide-4-2
 // #docregion providers-alternative-1
 :marked
   <a id="class-provider"></a>
@@ -762,15 +759,15 @@ code-example(format, language="html").
   These configuration objects aren't always instances of a class. They tend to be object hashes like this one:
 // #enddocregion tokens-non-class-deps-1
 +makeExample('dependency-injection/ts/app/app.config.ts','config','app/app-config.ts (excerpt)')(format='.')
-// #docregion tokens-non-class-deps-2
+
+// TypeScript only?
 :marked
   We'd like to make this `config` object available for injection.
   We know we can register an object with a [value provider](#value-provider).
   But what do we use for the token?
   We don't have a class to serve as a token. There is no `Config` class.
-// #enddocregion tokens-non-class-deps-2
 
-// begin Typescript only
+// Typescript only
 <a id="interface"></a>
 :marked
   ### Interfaces aren't valid tokens