update Dart API index, plus Dart guide chapters 3 & 4

public/docs/dart/latest/api/index.jade

@@ -2,9 +2,12 @@
   h2 Developer Preview
 
   p.
-    The Angular 2.0 API is currently in active development and not production ready.
+    The proposed Angular 2 API does not yet have Dart-specific documentation.
-    This page will showcase a preview of proposed methods to help further the discussion
+    However, because the Dart and JavaScript APIs are generated from the same source,
-    in the development community.
+    you might find the JavaScript API docs helpful:
+
+  p.text-center
+    <b><a href="/docs/js/latest/api/">Angular 2 API Preview (JavaScript)</a></b>
 
   .l-sub-section
     h3 Angular 1.X for Production

public/docs/dart/latest/guide/making-components.jade

@@ -1,10 +1,13 @@
 .l-main-section
   p.
-    As mentioned earlier, you build Angular applications as a tree of nested components.  You've seen how to create
+    As mentioned earlier, you build Angular applications as a tree of nested components.
-    a top-level component.  You add child components to a parent component by using them in the parent component's
+    You've seen how to create a top-level component.
-    template.
+    You add child components to a parent component by using them in
+    the parent component's template,
+    and by specifying the child component classes in the parent's list of directives.
   p.
-    Given a bootstrapping template with a <code>&lt;parent&gt;</code> tag in the body, you can create a parent
+    Given a bootstrapping template with a <code>&lt;parent&gt;</code> tag in the body,
+    you can create a parent
     component that uses a <code>&lt;child&gt;</code> component like so:
 
   pre.prettyprint.linenums.lang-dart
@@ -17,9 +20,9 @@
       @View(
         template: '''
           &lt;h1&gt;{{ message }}&lt;/h1&gt;
-          &lt;child&gt;&lt;/child&gt;
+          <span class="pnk">&lt;child&gt;&lt;/child&gt;</span>
       ''',
-        directives: const[ChildComponent]
+        directives: const[<span class="pnk">ChildComponent</span>]
       )
       class ParentComponent {
         String message = "I'm the parent";
@@ -43,8 +46,5 @@
         String message = "I'm the child";
       }
 
-  p.
-    Notice that in addition to using the <code>&lt;child&gt;</code> element in the parent template, you also need to
-    add <code>ChildComponent</code> in <code>ParentComponent</code>'s list of directives
   //p.
     [TODO: Motivate communication between components with iterator example that passes index to the child]

public/docs/dart/latest/guide/user-input.jade

@@ -1,40 +1,52 @@
 .l-main-section
   p.
-    You can make your application respond to user input by associating events with functions in your controller
+    Use the event syntax <strong>(<em>eventName</em>)</strong> to
-    using the event syntax using <strong>()</strong> to surround the name of an event.
+    make your application respond to user input.
   p.
-    For a particular control like an input you can have it call methods on your controller on keyup event like so:
+    You can specify the event handler—a method in the component controller—like this:
 
   pre.prettyprint.lang-html
     code.
       &lt;input (keyup)="myControllerMethod()"&gt;
   p.
-    As in previous examples, you can make element references available to other parts of the template as a local
+    As in previous examples, you can make element references available to
-    variable using the # syntax.  With this and events, we can do the old "update text as you type" example:
+    other parts of the template as a local
+    variable using the <b>#</b> syntax.
+    Using <code>#</code> and events,
+    you can write the old "update text as you type" example:
+    <!-- PENDING: make sure we use recommended word separation scheme.
+    my-name doesn't work, but my_name does. Would myName work? -->
 
   pre.prettyprint.lang-html
     code.
-      &lt;input #my-name (keyup)&gt;
+      &lt;input #myname (keyup)&gt;
-      &lt;p&gt;{{my-name.value}}&lt;/p&gt;
+      &lt;p&gt;{{myname.value}}&lt;/p&gt;
 
   p.text-body(ng-non-bindable).
-    The <code>#my-name</code> creates a local variable in the template that we'll refer to below in the
+    In that example, <code>#myname</code> creates a local variable in the template that
-    <code>&lt;p&gt;</code> element.  The <code>(keyup)</code> tells Angular to trigger updates when it gets a keyup
+    the <code>&lt;p&gt;</code> element can refer to.
-    event.  And the <code>{{my-name.value}}</code> binds the text node of the  <code>&lt;p&gt;</code> element to the
+    The <code>(keyup)</code> tells Angular to trigger updates when it gets a keyup
+    event.  And <code>{{myname.value}}</code> binds the text node of the
+    <code>&lt;p&gt;</code> element to the
     input's value property.
-  p Let's do something a little more complex where users enter items and add them to a list like this:
+
+  p.
+    Let's do something a little more complex, where the user enters items
+    that the app adds to a list:
   figure.image-display
     img(src='user-input-example1.png')
 
 
 .l-main-section
-  h2#section-create-an-array-property Create an array property
+  h2#section-create-an-array-property Create a list property
   p.
-    With the default bootstrapping in place, create a TodoController class that will manage interactions with the
+    With the default files in place,
-    list. Inside TodoController, add an array with an initial list of items.  Then add a method that pushes new items
+    create a TodoController class to manage interactions with the
-    on the array when called.
+    list. Inside TodoController, add a list with some initial items.
+    Then add a method that adds new items
+    to the list.
 
-  pre.prettyprint.linenums.lang-dart
+  pre.prettyprint.lang-dart
     code.
       class TodoList {
         List&lt;String&gt; todos =
@@ -42,21 +54,26 @@
 
         addTodo(String todo) {
           todos.add(todo);
-          }
+        }
+      }
 
 .callout.is-helpful
   header Production Best Practice
   p.
-      As with the previous example, in a production application you will separate your model out into another class
+      As shown in the previous example, a production application you would
-      and inject it into <code>TodoController</code>.  We've omitted it here for brevity.
+      separate the model out into another class
+      and inject it into <code>TodoController</code>.
+      We've omitted that here for brevity.
+
+<br><br><!-- PENDING: fix formatting of main sections after callouts -->
 
 .l-main-section
   h2#section-display-the-list-of-todos Display the list of todos
   p.
-    Using the <code>*for</code> iterator, create an <code>&lt;li&gt;</code> for each item in the todos array and set
+    Using the <code>*for</code> iterator, create an <code>&lt;li&gt;</code> for each item in the todos list and set
     its text to the value.
 
-  pre.prettyprint.linenums.lang-html
+  pre.prettyprint.lang-html
     code.
       &lt;ul&gt;
          &lt;li *for=&quot;#todo of todos&quot;&gt;
@@ -74,64 +91,126 @@
     code.
       &lt;input #todotext&gt;
   p.
-    Lastly, specify the target of the click event binding as your controller's <code>addTodo()</code> method and pass
+    Specify the target of the click event binding as your controller's
-    it the value. Since you created a reference called <code>todotext</code>, you can get the value with
+    <code>addTodo()</code> method and pass
-    <code>todotext.value.</code>
+    it the value. Since you created a reference called <code>todotext</code>,
+    you can get the value with <code>todotext.value.</code>
 
   pre.prettyprint.lang-html
     code.
         &lt;button (click)="addTodo(todotext.value)"&gt;Add Todo&lt;/button&gt;
 
-  p And then create the doneTyping() method on TodoList and handle adding the todo text.
+  p.
+    To make pressing Enter do something useful,
+    you can add a keyup event handler to the input field.
+    This event handler uses APIs defined in
+    <a href="https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:html">dart:html</a>,
+    so be sure to import that library.
+
+  .code-box
+    pre.prettyprint.lang-dart(data-name="todo_list.dart")
+      code.
+        // In the template:
+        &lt;input #todotext (keyup)="doneTyping(\$event)"&gt;
+
+        // In the component controller class:
+        doneTyping(KeyboardEvent event) {
+          if (event.keyCode == KeyCode.ENTER) {
+            InputElement e = event.target;
+            addTodo(e.value);
+            e.value = null;
+          }
+        }
+    pre.prettyprint.lang-dart(data-name="main.dart")
+      code.
+        library user_input;
+
+        import 'dart:html';
+        ...
 
-  pre.prettyprint.lang-dart
-    code.
-      doneTyping(KeyboardEvent event) {
-         if (event.which == 13) {
-           InputElement e = event.target;
-           addTodo(e.value);
-           e.value = null;
-         }
-       }
 
 .l-main-section
-  h2#section-final-code Final Code
+  h2#section-final-code Final code
-  p Here's the final <code>todo_list.dart</code>
-  pre.prettyprint.lang-dart
-    code.
-      part of user_input;
 
-      @Component(
+  .code-box
-        selector: 'todo-list'
+    pre.prettyprint.lang-dart(data-name="todo_list.dart")
-      )
+      code.
-      @View(
+        // web/todo_list.dart
-        // Without r before ''' (a raw string), $event breaks Angular!
+        part of user_input;
-        // An alternative is to use \$event instead.
-        template: '''
-          &lt;ul&gt;
-            &lt;li *for=&quot;#todo of todos&quot;&gt;
-              {{ todo }}
-            &lt;/li&gt;
-          &lt;/ul&gt;
 
-          &lt;input #todotext (keyup)="doneTyping($event)"&gt;
+        @Component(
-          &lt;button (click)="addTodo(todotext.value)"&gt;Add Todo&lt;/button&gt;
+          selector: 'todo-list'
-         ''',
+        )
-           directives: const[For]
+        @View(
-         )
+          // Without r before ''' (a raw string), $event breaks Angular.
-         class TodoList {
+          // An alternative to a raw string is to use \$event instead.
-           List&lt;String&gt; todos =
+          template: r'''
-             ['Eat breakfast', 'Walk dog', 'Breathe', 'Learn Angular'];
+            &lt;ul&gt;
+              &lt;li *for=&quot;#todo of todos&quot;&gt;
+                {{ todo }}
+              &lt;/li&gt;
+            &lt;/ul&gt;
 
-           addTodo(String todo) {
+            &lt;input #todotext (keyup)="doneTyping($event)"&gt;
-             todos.add(todo);
+            &lt;button (click)="addTodo(todotext.value)"&gt;Add Todo&lt;/button&gt;
-           }
+           ''',
+             directives: const[For]
+        )
+        class TodoList {
+          List&lt;String&gt; todos =
+            ['Eat breakfast', 'Walk dog', 'Breathe', 'Learn Angular'];
 
-           doneTyping(KeyboardEvent event) {
+          addTodo(String todo) {
-             if (event.which == 13) {
+            todos.add(todo);
-               InputElement e = event.target;
+          }
-               addTodo(e.value);
+
-               e.value = null;
+          doneTyping(KeyboardEvent event) {
-             }
+            if (event.keyCode == KeyCode.ENTER) {
-           }
+              InputElement e = event.target;
-         }
+              addTodo(e.value);
+              e.value = null;
+            }
+          }
+        }
+    pre.prettyprint.lang-dart(data-name="main.dart")
+      code.
+        // web/main.dart
+        library user_input;
+
+        import 'dart:html';
+
+        import 'package:angular2/angular2.dart';
+        import 'package:angular2/src/reflection/reflection.dart' show reflector;
+        import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities;
+
+        part 'todo_list.dart';
+
+        main() {
+          reflector.reflectionCapabilities = new ReflectionCapabilities();
+          bootstrap(TodoList);
+        }
+    pre.prettyprint.lang-html(data-name="html")
+      code.
+        &lt;!-- web/index.html --&gt;
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+          &lt;head&gt;
+            &lt;link rel=&quot;stylesheet&quot; href=&quot;style.css&quot;&gt;
+          &lt;/head&gt;
+          &lt;body&gt;
+
+            &lt;todo-list&gt;&lt;/todo-list&gt;
+
+            &lt;script type=&quot;application/dart&quot; src=&quot;main.dart&quot;&gt;&lt;/script&gt;
+            &lt;script src=&quot;packages/browser/dart.js&quot;&gt;&lt;/script&gt;
+          &lt;/body&gt;
+        &lt;/html&gt;
+    pre.prettyprint.lang-yaml(data-name="yaml")
+      code.
+        # pubspec.yaml
+        name: user_input
+        description: Dart version of Angular 2 example, Responding to User Input
+        version: 0.0.1
+        dependencies:
+          angular2: 2.0.0-alpha.20
+          browser: any

public/docs/js/latest/api/index.jade

@@ -4,7 +4,7 @@
     header Developer Preview
     p.
       The Angular 2.0 API is currently in active development and not production ready.
-      This page will showcase a preview of proposed methods to help further the discussion
+      This page showcases a preview of proposed methods to help further the discussion
       in the development community. If you're building a production app today, please
       <a href="https://docs.angularjs.org/api">use Angular 1.X</a>.