docs(architecture): add Jade blocks for Dart, and other tweaks (#2990)

Author: chalin

.gitignore

@@ -35,3 +35,4 @@ link-checker-results.txt
 /dist
 /public/docs/dart
 /public/docs/ts/_cache
+/public/docs/_examples/*/dart

public/docs/ts/latest/guide/architecture.jade

@@ -48,115 +48,119 @@ figure
   ## Modules
 figure
   img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
-:marked
-  Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
-
-  _Angular modules_ are a big deal. 
-  This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
 
-<br class="l-clear-both"><br>
-:marked
-  Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"), 
-  conventionally named `AppModule`.
+block angular-modules
+  :marked
+    Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
 
-  While the _root module_ may be the only module in a small application, most apps have many more 
-  _feature modules_, each a cohesive block of code dedicated to an application domain,
-  a workflow, or a closely related set of capabilities. 
+    _Angular modules_ are a big deal. 
+    This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
 
-  An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
-.l-sub-section
+  <br class="l-clear-both"><br>
   :marked
-    Decorators are functions that modify JavaScript classes.
-    Angular has many decorators that attach metadata to classes so that it knows
-    what those classes mean and how they should work.
-    <a href="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0" target="_blank">
-    Learn more</a> about decorators on the web.
-:marked
-  `NgModule` is a decorator function that takes a single metadata object whose properties describe the module. 
-  The most important properties are:
-  * `declarations` - the _view classes_ that belong to this module.
-  Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
+    Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"), 
+    conventionally named `AppModule`.
+
+    While the _root module_ may be the only module in a small application, most apps have many more 
+    _feature modules_, each a cohesive block of code dedicated to an application domain,
+    a workflow, or a closely related set of capabilities. 
+
+    An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
+  .l-sub-section
+    :marked
+      Decorators are functions that modify JavaScript classes.
+      Angular has many decorators that attach metadata to classes so that it knows
+      what those classes mean and how they should work.
+      <a href="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0" target="_blank">
+      Learn more</a> about decorators on the web.
+  :marked
+    `NgModule` is a decorator function that takes a single metadata object whose properties describe the module. 
+    The most important properties are:
+    * `declarations` - the _view classes_ that belong to this module.
+    Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
 
-  * `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
+    * `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
 
-  * `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
+    * `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
 
-  * `providers` - creators of [services](#services) that this module contributes to
-  the global collection of services; they become accessible in all parts of the app.
+    * `providers` - creators of [services](#services) that this module contributes to
+    the global collection of services; they become accessible in all parts of the app.
 
-  * `bootstrap` - the main application view, called the _root component_, 
-  that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
+    * `bootstrap` - the main application view, called the _root component_, 
+    that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
 
-  Here's a simple root module:
-+makeExample('app/mini-app.ts', 'module', 'app/app.module.ts')(format='.')
+    Here's a simple root module:
+  +makeExample('app/mini-app.ts', 'module', 'app/app.module.ts')(format='.')
 
-.l-sub-section
+  .l-sub-section
+    :marked
+      The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module. 
   :marked
-    The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module. 
-:marked
-  Launch an application by _bootstrapping_ its root module. 
-  During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
-    
-+makeExample('app/main.ts', '', 'app/main.ts')(format='.')
+    Launch an application by _bootstrapping_ its root module. 
+    During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
+      
+  +makeExample('app/main.ts', '', 'app/main.ts')(format='.')
 
-:marked
-  ### Angular modules vs. JavaScript modules
+  :marked
+    ### Angular modules vs. JavaScript modules
 
-  The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular.
+    The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular.
 
-  JavaScript also has its own module system for managing collections of JavaScript objects.
-  It's completely different and unrelated to the Angular module system.
-  
-  In JavaScript each _file_ is a module and all objects defined in the file belong to that module.
-  The module declares some objects to be public by marking them with the `export` key word. 
-  Other JavaScript modules use *import statements* to access public objects from other modules.
+    JavaScript also has its own module system for managing collections of JavaScript objects.
+    It's completely different and unrelated to the Angular module system.
+    
+    In JavaScript each _file_ is a module and all objects defined in the file belong to that module.
+    The module declares some objects to be public by marking them with the `export` key word. 
+    Other JavaScript modules use *import statements* to access public objects from other modules.
 
-+makeExample('app/app.module.ts', 'imports', '')(format='.')
-+makeExample('app/app.module.ts', 'export', '')(format='.')
-  
-.l-sub-section
+  +makeExample('app/app.module.ts', 'imports', '')(format='.')
+  +makeExample('app/app.module.ts', 'export', '')(format='.')
+    
+  .l-sub-section
+    :marked
+      <a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
   :marked
-    <a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
-:marked
-  These are two different and _complementary_ module systems. Use them both to write your apps.
+    These are two different and _complementary_ module systems. Use them both to write your apps.
 
+:marked
   ### Angular libraries
 
 figure
   img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
 
-:marked
-  Angular ships as a collection of JavaScript modules. You can think of them as library modules. 
-
-  Each Angular library name begins with the `!{_at_angular}` prefix.
-  
-  You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
-<br class="l-clear-both"><br>
-:marked
-  For example, import Angular's `Component` decorator from the `@angular/core` library like this:
-+makeExample('app/app.component.ts', 'import', '')(format='.')
-:marked
-  You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
-+makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
-:marked
-  In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
-+makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
-:marked
-  In this way you're using both the Angular and JavaScript module systems _together_.
+block angular-libraries
+  :marked
+    Angular ships as a collection of JavaScript modules. You can think of them as library modules. 
 
-  It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
-  Hang in there. The confusion yields to clarity with time and experience.
+    Each Angular library name begins with the `!{_at_angular}` prefix.
+    
+    You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
+    <br class="l-clear-both"><br>
 
-.l-sub-section
+    For example, import Angular's `Component` decorator from the `@angular/core` library like this:
+  +makeExample('app/app.component.ts', 'import', '')(format='.')
+  :marked
+    You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
+  +makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
+  :marked
+    In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
+  +makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
   :marked
-    Learn more from the [Angular modules](ngmodule.html) page.
+    In this way you're using both the Angular and JavaScript module systems _together_.
+
+    It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
+    Hang in there. The confusion yields to clarity with time and experience.
+
+  .l-sub-section
+    :marked
+      Learn more from the [Angular modules](ngmodule.html) page.
 
 .l-hr 
 
-.l-main-section
+.l-main-section#components
 :marked
-  <a id="components"></a>
   ## Components
+
 figure
   img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
 
@@ -169,7 +173,6 @@ figure
   * The list of heroes.
   * The hero editor.
 
-
   You define a component's application logic&mdash;what it does to support the view&mdash;inside a class.
   The class interacts with the view through an API of properties and methods.
 
@@ -253,7 +256,7 @@ block ts-decorator
     Here are a few of the possible `@Component` configuration options:
 
 :marked
-  - `moduleId`: sets the source of the base address (`module.id`) for module-relative URLs such as the `templateUrl`.
+  <ul if-docs="ts"><li>`moduleId`: sets the source of the base address (`module.id`) for module-relative URLs such as the `templateUrl`.</ul>
 
   - `selector`: CSS selector that tells Angular to create and insert an instance of this component
   where it finds a `<hero-list>` tag in *parent* HTML.
@@ -262,6 +265,9 @@ block ts-decorator
 
   - `templateUrl`: module-relative address of this component's HTML template, shown [above](#templates).
 
+block dart-directives
+
+:marked
   - `providers`: !{_array} of **dependency injection providers** for services that the component requires.
   This is one way to tell Angular that the component's constructor requires a `HeroService`
   so it can get the list of heroes to display. 
@@ -305,7 +311,7 @@ figure
 
 :marked
   * The `{{hero.name}}` [*interpolation*](displaying-data.html#interpolation)
-  displays the component's `hero.name` property value within the `<li>` tags.
+  displays the component's `hero.name` property value within the `<li>` element.
 
   * The `[hero]` [*property binding*](template-syntax.html#property-binding) passes the value of `selectedHero` from
   the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`.
@@ -349,12 +355,10 @@ figure
   Angular templates are *dynamic*. When Angular renders them, it transforms the DOM
   according to the instructions given by **directives**.
 
-  A directive is a class with directive metadata. In !{_Lang}, apply the `@Directive` !{_decorator}
-  to attach metadata to the class.
-<br class="l-clear-both">
-:marked
+  A directive is a class with a `@Directive` !{_decorator}.
   A component is a *directive-with-a-template*;
   a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features.
+  <br class="l-clear-both">
 
 .l-sub-section
   :marked
@@ -377,7 +381,6 @@ figure
   * [`*ngIf`](displaying-data.html#ngIf) includes the `HeroDetail` component only if a selected hero exists.
 
 block dart-bool
-  //- N/A
 
 :marked
   **Attribute** directives alter the appearance or behavior of an existing element.
@@ -491,17 +494,19 @@ figure
   In brief, you must have previously registered a **provider** of the `HeroService` with the injector.
   A provider is something that can create or return a service, typically the service class itself.
 
-  You can register providers in modules or in components.
-  
-  In general, add providers to the [root module](#module) so that
-  the same instance of a service is available everywhere.
+block registering-providers
+  :marked
+    You can register providers in modules or in components.
+    
+    In general, add providers to the [root module](#module) so that
+    the same instance of a service is available everywhere.
 
-+makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.')
+  +makeExcerpt('app/app.module.ts (module providers)', 'providers')
 
 :marked
   Alternatively, register at a component level in the `providers` property of the `@Component` metadata:
 
-+makeExample('app/hero-list.component.ts', 'providers', 'app/hero-list.component.ts (component providers)')(format='.')
++makeExcerpt('app/hero-list.component.ts (component providers)', 'providers')
 
 :marked
   Registering at a component level means you get a new instance of the