midway through incorporating thso's comments...

Author: kwalrath

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

@@ -112,7 +112,17 @@ include ../_util-fns
 +includeShared('{ts}', 'di-service-service-2')
 +includeShared('{ts}', 'di-injectable-1')
 +includeShared('{ts}', 'di-injectable-2')
-
+.callout.is-critical
+  header Always include the parentheses
+  :marked
+    Always use `@Injectable()`, not just `@Injectable`.
+    A metadata annotation must be either a reference to a
+    compile-time constant variable or a call to a constant
+    constructor such as `Injectable()`.
+    If we forget the parentheses, the analyzer will complain:
+    "Annotation creation must have arguments". If we try to run the
+    app anyway, it won't work, and the console will say
+    "expression must be a compile-time constant".
 +includeShared('{ts}', 'logger-service-1')
 +makeExample(
   'dependency-injection/dart/lib/logger_service.dart',null, 'lib/logger_service')
@@ -152,8 +162,9 @@ include ../_util-fns
     For that reason, you can't call functions to get values
     to use within an annotation.
     Instead, you use constant literals or constant constructors.
-    For example, a TypeScript or JavaScript program might use
-    `provide(Logger, {useClass: BetterLogger})` or, equivalently,
+    For example, a TypeScript program might use the
+    function call `provide(Logger, {useClass: BetterLogger})`,
+    which is equivalent to the TypeScript code
     `new Provider(Logger, {useClass: BetterLogger})`.
     A Dart annotation would instead use the constant value `const Provider(Logger, useClass: BetterLogger)`.
 +includeShared('{ts}', 'providers-alternative-2')

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

@@ -430,12 +430,13 @@ include ../_util-fns
 
     We *can* add it if we really want to. It isn't necessary because
     the `HeroesComponent` is already #{decorated} with `@Component`. #{any_decorator}
-
-.alert.is-critical
+// #enddocregion di-injectable-2
+.callout.is-critical
+  header Always include the parentheses
   :marked
-    **Always include the parentheses!** Always use `@Injectable()`.
+    Always use `@Injectable()`, not just `@Injectable`.
     Our application will fail mysteriously if we forget the parentheses.
-// #enddocregion di-injectable-2
+
 // #docregion logger-service-1
 .l-main-section
 :marked
@@ -528,11 +529,14 @@ code-example(format, language="html").
 // #enddocregion providers-1
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-logger')
 // #docregion providers-2
+- var lang = current.path[1]
+- var implements = lang == 'dart' ? 'implements' : 'looks and behaves like a '
+ #{decoration}
 :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.
 
-  There are many ways to *provide* something that looks and behaves like a `Logger`.
+  There are many ways to *provide* something that #{implements} `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.