Part way through PR comments

Author: kapunahelewong

public/docs/ts/latest/guide/reactive-forms.jade

@@ -16,11 +16,11 @@ a#toc
   - [Import the _ReactiveFormsModule_](#import)
   - [Update the app to use the form component](#update)
   - [Introduction to _FormBuilder_](#formbuilder)
-  - [Group _FormControls_](#grouping)
+  - [Nested FormGroups](#grouping)
   - [Inspect _FormControl_ properties](#properties)
   - [Set form model data using _setValue_ and _patchValue_](#set-data)
   - [Use _FormArray_ to present an array of _FormGroups_](#form-array)
-  - [Watch control changes](#watch-control)
+  - [Observe control changes](#observe-control)
   - [Save form data](#save)
 
   Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker">Reactive Forms live-example</live-example>.
@@ -85,42 +85,22 @@ a#intro
   You don't push and pull data values. Angular handles that for you with `ngModel`.
   Angular updates the mutable _data model_ with user changes as they happen.
 
-  Both data binding and the mutable _data model_ are contrary to reactive principles.
-  In fact, the `ngModel` directive is only available in the `FormsModule`, not in the `ReactiveFormsModule`.
-
+  When writing in a reactive style, you determine the timing and flow of data between 
+  the data model and the screen. You rarely, if ever, use two-way data binding. 
+  For this reason, the ngModel directive is not part of the ReactiveFormsModule.
+  
   These differences reflect two architectural paradigms, 
   with their own strengths and weaknesses,
   and you are free to choose between them.
 
   The balance of this _reactive forms_ guide assumes the _reactive_ paradigm and 
-  concentrates exclusively on the reactive forms technique. For 
+  concentrates exclusively on the reactive forms techniques. For 
   information on _template driven forms_, see the [Template Guide](forms.html).
 
-  You'll learn about reactive forms by building one from scratch,
-  with instances of the Angular form classes.
-
-  ### Essential form classes
-
-  Before you begin, it may be helpful to read a brief description of the core form classes.
-  
-  * [_AbstractControl_](../api/forms/index/AbstractControl-class.html-class.html "API Reference: AbstractControl")
-  is the abstract base class for the three concrete form control classes: 
-  `FormControl`, `FormGroup`, and `FormArray`.
-  It provides their common behaviors and properties, some of which are _observable_.
-
-  * [_FormControl_](../api/forms/index/FormControl-class.html "API Reference: FormControl") 
-  tracks the value and validity status of an _individual_ form control.
-  It corresponds to an HTML form control such as an input box or selector.
-
-  * [_FormGroup_](../api/forms/index/FormGroup-class.html "API Reference: FormGroup")
-  tracks the value and validity state of a _group_ of `AbstractControl` instances.
-  The group's properties include its child controls.
-  The top-level form in your component is a `FormGroup`.
-
-  * [_FormArray_](../api/forms/index/FormArray-class.html "API Reference: FormArray")
-  tracks the value and validity state of a numerically indexed _array_ of `AbstractControl` instances.
+  You'll learn about reactive forms by building one from scratch.
 
-  You'll learn more about these classes as you build your first reactive form.
+  In the next section, you'll prepare your project for reactive forms.
+  Then you'll [learn about the Angular form classes](#essentials) and how to use them in a reactive form.
 
 .l-main-section
 a#setup
@@ -170,7 +150,7 @@ a#create-component
 +makeExample('reactive-forms/ts/app/hero-detail-versions.component.ts', 'v1','app/hero-detail.component.ts (excerpt)')(format=".")
 
 :marked
-  Inside the `FormGroup`, called `heroForm`, is a `FormControl` called `name`.
+  Here you are creating a `FormGroup` called `heroForm` with a child `FormControl` called `name`.
   It will be bound in the template to an HTML `input` box for the hero name. 
 
   A `FormControl` constructor accepts three, optional arguments: 
@@ -195,9 +175,11 @@ a#create-template
 :marked
   The `novalidate` attribute in the `<form>` element prevents the browser 
   from attempting native HTML validations. 
-  The `[formGroup]="heroForm"` tells Angular that the form element
-  is associated with the `heroForm` property of the component class.
-  The `formControlName="name"` associates the `input` element with the `name` control inside the `heroForm`.
+
+  `formGroup` is a reactive form directive that takes an existing 
+  `FormGroup` instance and associates it with an HTML element. 
+  In this case, it will associate the `FormGroup` we saved as 
+  `heroForm` with the form element.
 
 .l-sub-section
   :marked
@@ -210,9 +192,8 @@ a#import
 :marked
   ## Import the _ReactiveFormsModule_
 
-  The `HeroDetailComponent` template uses directives from 
-  the `ReactiveFormsModule` in the `@angular/forms` library
-  so you must add it to the `imports` array of the `NgModule` that declares that component.
+  The HeroDetailComponent template uses `formGroup` and `formControlName` 
+  directives from the `ReactiveFormsModule`.
 
   In this sample, you declare the `HeroDetailComponent` in the `AppModule`.
   Therefore, do the following three things in `app.module.ts`:
@@ -230,6 +211,31 @@ a#update
   Revise the `AppComponent` template so it displays the `HeroDetailComponent`.
 +makeExample('reactive-forms/ts/app/app.component.1.ts', '','app/app.component.ts')(format=".")
 
+a#essentials
+:marked
+  ### Essential form classes
+  It may be helpful to read a brief description of the core form classes.
+  
+  * [_AbstractControl_](../api/forms/index/AbstractControl-class.html-class.html "API Reference: AbstractControl")
+  is the abstract base class for the three concrete form control classes: 
+  `FormControl`, `FormGroup`, and `FormArray`.
+  It provides their common behaviors and properties, some of which are _observable_.
+
+  * [_FormControl_](../api/forms/index/FormControl-class.html "API Reference: FormControl") 
+  tracks the value and validity status of an _individual_ form control.
+  It corresponds to an HTML form control such as an input box or selector.
+
+  * [_FormGroup_](../api/forms/index/FormGroup-class.html "API Reference: FormGroup")
+  tracks the value and validity state of a _group_ of `AbstractControl` instances.
+  The group's properties include its child controls.
+  The top-level form in your component is a `FormGroup`.
+
+  * [_FormArray_](../api/forms/index/FormArray-class.html "API Reference: FormArray")
+  tracks the value and validity state of a numerically indexed _array_ of `AbstractControl` instances.
+
+  You'll learn more about these classes as you work through this guide.
+
+
 :marked
   ### Style the app
   You used bootstrap CSS classes in the template HTML of both the `AppComponent` and the `HeroDetailComponent`.
@@ -270,7 +276,6 @@ figure.image-display
   Great! You have the basics of a form. 
 
   In real life apps, forms get big fast. 
-  The way you are creating `FormControls` currently is both tedious and hard to maintain. 
   `FormBuilder` makes form development and maintenance easier.
 
 
@@ -288,7 +293,7 @@ a#formbuilder
 
   * Explicitly declare the type of the `heroForm` property to be `FormGroup`; you'll initialize it later.
   * Inject a `FormBuilder` into the constructor.
-  * Add a new `createForm` method that uses the `FormBuilder` to define the `heroForm`.
+  * Add a new method that uses the `FormBuilder` to define the `heroForm`; call it `createForm`.
   * Call `createForm` in the constructor.
 
   The revised `HeroDetailComponent` looks like this:
@@ -326,12 +331,13 @@ a#formbuilder
 .l-main-section
 a#grouping
 :marked
-  ### Group FormControls
+  ### Nested FormGroups
 
   This form is getting big and unwieldy. You can group some of the related `FormControls` 
-  into another `FormGroup`. The `street`, `city`, `state`, and `zip` are properties 
+  into a nested `FormGroup`. The `street`, `city`, `state`, and `zip` are properties 
   that would make a good _address_ `FormGroup`.
-  Grouping in this way allows you to mirror the hierarchical structure of the data model 
+  Nesting groups and controls in this way allows you to 
+  mirror the hierarchical structure of the data model 
   and helps track validation and state for related sets of controls. 
 
   You used the `FormBuilder` to create one `FormGroup` in this component called `heroForm`.
@@ -403,7 +409,7 @@ table(width="100%")
     td <code>myControl.status</code>
     td
       :marked
-        whether the `FormControl` is `valid`, 
+        the validity of a `FormControl`. Possible values: `valid`, 
          `invalid`, `pending`, or `disabled`.
   tr
     td <code>myControl.pristine</code>
@@ -446,9 +452,6 @@ a#data-model-form-model
 
   2. User changes flow from the DOM elements to the _form model_, not to the _data model_.
   The form controls never update the _data model_.
-  In the reactive paradigm, the data model is presumed to be _immutable_
-  and it's your responsibility to preserve that immutability constraint.
-  Kara, Deborah suggested running this by you. Could you confirm that this is the case?
 
   The _form_ and _data_ model structures need not match exactly.
   You often present a subset of the _data model_ on a particular screen.
@@ -482,7 +485,9 @@ a#data-model-form-model
 a#set-data
 :marked
   ## Populate the form model with _setValue_ and _patchValue_
-  You can initialize control values in a `FormGroup` using `setValue` or `patchValue`.
+  Previously you created a control and initialized its value at the same time. 
+  You can also initialize or reset the values _later_ with the 
+  `setValue` and `patchValue` methods.
 
   ### _setValue_
   With **`setValue`**, you assign _every_ form control value _at once_
@@ -491,9 +496,13 @@ a#set-data
 +makeExample('reactive-forms/ts/app/hero-detail-versions.component.ts', 'set-value','app/hero-detail.component.ts (excerpt)')(format=".")
 :marked
   The `setValue` method checks the data object thoroughly before assigning any form control values.
-  It rejects a data object that doesn't match the `FormGroup` structure.
-  It rejects a data object if it is missing values for any control in the group.
-  It does return helpful errors.
+
+  - It rejects a data object that doesn't match the `FormGroup` structure.
+  - It rejects a data object if it is missing values for any control in the group.
+  - It returns helpful error messages.
+
+  If you have a typo or nested controls incorrectly, `setValue` will catch 
+  the error and report it clearly. `patchValue` will fail silently.
 
   Notice that you can _almost_ use the entire `hero` as the argument to `setValue`
   because its shape is similar to the component's `FormGroup` structure.
@@ -512,7 +521,8 @@ a#set-data
 
 :marked
   With **`patchValue`** you have more flexibility to cope with wildly divergent data and form models.
-  But unlike `setValue`,  `patchValue` cannot check for missing control values and does not return errors.
+  But unlike `setValue`,  `patchValue` cannot check for missing control 
+  values and does not throw helpful errors.
 
   ### When to set form model values (_ngOnChanges_)
 
@@ -654,7 +664,7 @@ a#form-array
   The `HeroDetailComponent` should be able to display, add, and remove items from the _secretLairs_ `FormArray`.
 
   Use the `FormGroup.get` method to acquire a reference to that `FormArray`.
-  Wrap the expression in a `secretLairs` convenience property for clairity and re-use.
+  Wrap the expression in a `secretLairs` convenience property for clarity and re-use.
 +makeExample('reactive-forms/ts/app/hero-detail-versions.component.ts', 'get-secret-lairs','app/hero-detail.component.ts (secretLayers property)')(format=".")
 
 :marked
@@ -675,7 +685,7 @@ a#form-array
   1. The source of the repeated items is the `FormArray.controls`, not the `FormArray` itself. 
   Each control is an _address_ `FormGroup`, exactly what the previous (now repeated) template HTML expected.
 
-  1. Each repeated `FormGroup` needs a unique `FormGroupName` which must be the index of the `FormGroup` in the `FormArray`.
+  1. Each repeated `FormGroup` needs a unique `formGroupName` which must be the index of the `FormGroup` in the `FormArray`.
   You'll re-use that index to compose a unique label for each address.
 
   Here's the skeleton for the _secret lairs_ section of the HTML template:
@@ -724,9 +734,9 @@ figure.image-display
   For extra credit, write a `removeLair` method and wire it to a button on the repeating address HTML.
 
 .l-main-section
-a#watch-control
+a#observe-control
 :marked
-  ## Watch control changes
+  ## Observe control changes
 
   Angular calls `ngOnChanges` when the user picks a hero in the parent `HeroListComponent`.
   Picking a hero changes the `HeroDetailComponent.hero` input property.