From 0075017b43a37d06780cc245c3326212d15fd6bd Mon Sep 17 00:00:00 2001
From: Judy Bogart <jbogart@gmail.com>
Date: Wed, 4 Mar 2020 16:40:56 -0800
Subject: [PATCH] docs: update reactive forms page (#35969)

PR Close #35969
---
 aio/content/guide/deprecations.md             |  68 +++++-
 aio/content/guide/reactive-forms.md           | 194 ++++++++++++------
 .../form_control_directive.ts                 |  79 +------
 .../reactive_directives/form_control_name.ts  |  72 +------
 packages/forms/src/form_providers.ts          |   7 +-
 packages/forms/src/model.ts                   |   3 +-
 6 files changed, 210 insertions(+), 213 deletions(-)

diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md
index 6d28414fd0..880affa372 100644
--- a/aio/content/guide/deprecations.md
+++ b/aio/content/guide/deprecations.md
@@ -117,7 +117,7 @@ Tip: In the [API reference section](api) of this doc site, deprecated APIs are i
 
 | API | Replacement | Deprecation announced | Notes |
 | --- | ----------- | --------------------- | ----- |
-| [`ngModel` with reactive forms](#ngmodel-reactive) | See [FormControlDirective usage notes](api/forms/FormControlDirective#use-with-ngmodel) | v6 | none |
+| [`ngModel` with reactive forms](#ngmodel-reactive) | [`FormControlDirective`](api/forms/FormControlDirective) | v6 | none |
 
 {@a router}
 ### @angular/router
@@ -189,9 +189,71 @@ The `<template>` tag was deprecated in v4 to avoid colliding with the DOM's elem
 {@a ngmodel-reactive}
 ### ngModel with reactive forms
 
-Support for using the `ngModel` input property and `ngModelChange` event with reactive form directives was deprecated in version 6.
+Support for using the `ngModel` input property and `ngModelChange` event with reactive
+form directives has been deprecated in Angular v6 and will be removed in a future version
+of Angular.
 
-For more information, see the usage notes for [`FormControlDirective`](api/forms/FormControlDirective#use-with-ngmodel) and [`FormControlName`](api/forms/FormControlName#use-with-ngmodel).
+Now deprecated:
+
+```html
+<input [formControl]="control" [(ngModel)]="value">
+```
+
+```ts
+this.value = 'some value';
+```
+
+This has been deprecated for several reasons. First, developers have found this pattern
+confusing. It seems like the actual `ngModel` directive is being used, but in fact it's
+an input/output property named `ngModel` on the reactive form directive that
+approximates some, but not all, of the directive's behavior.
+It allows getting and setting a value and intercepting value events, but
+some of `ngModel`'s other features, such as
+delaying updates with`ngModelOptions` or exporting the directive, don't work.
+
+In addition, this pattern mixes template-driven and reactive forms strategies, which
+prevents taking advantage of the full benefits of either strategy.
+Setting the value in the template violates the template-agnostic
+principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in
+the class removes the convenience of defining forms in the template.
+
+To update your code before support is removed, you'll want to decide whether to stick
+with reactive form directives (and get/set values using reactive forms patterns) or
+switch over to template-driven directives.
+
+After (choice 1 - use reactive forms):
+
+```html
+<input [formControl]="control">
+```
+
+```ts
+this.control.setValue('some value');
+```
+
+After (choice 2 - use template-driven forms):
+
+```html
+<input [(ngModel)]="value">
+```
+
+```ts
+this.value = 'some value';
+```
+
+By default, when you use this pattern, you will see a deprecation warning once in dev
+mode. You can choose to silence this warning by providing a config for
+`ReactiveFormsModule` at import time:
+
+```ts
+imports: [
+  ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
+]
+```
+
+Alternatively, you can choose to surface a separate warning for each instance of this
+pattern with a config value of `"always"`. This may help to track down where in the code
+the pattern is being used as the code is being updated.
 
 
 {@a reflectiveinjector}
diff --git a/aio/content/guide/reactive-forms.md b/aio/content/guide/reactive-forms.md
index 4e21778e2c..ca73e5fad4 100644
--- a/aio/content/guide/reactive-forms.md
+++ b/aio/content/guide/reactive-forms.md
@@ -1,36 +1,54 @@
 # Reactive forms
 
-*Reactive forms* provide a model-driven approach to handling form inputs whose values change over time. This guide shows you how to create and update a simple form control, progress to using multiple controls in a group, validate form values, and implement more advanced forms.
+Reactive forms provide a model-driven approach to handling form inputs whose values change over time. This guide shows you how to create and update a basic form control, progress to using multiple controls in a group, validate form values, and create dynamic forms where you can add or remove controls at run time.
 
+<div class="alert is-helpful">
 
+Try this <live-example title="Reactive Forms in Stackblitz">Reactive Forms live-example</live-example>.
 
-{@a toc}
+</div>
 
-Try the <live-example title="Reactive Forms in Stackblitz">Reactive Forms live-example</live-example>.
+**Prerequisites**
+
+Before going further into reactive forms, you should have a basic understanding of the following:
+
+* TypeScript programming.
+* Angular app-design fundamentals, as described in [Angular Concepts](guide/architecture "Introduction to Angular concepts.").
+* The form-design concepts that are presented in [Introduction to Forms](guide/forms-overview "Overview of Angular forms.").
 
 {@a intro}
 
-## Introduction to reactive forms
+## Overview of reactive forms
 
-Reactive forms use an explicit and immutable approach to managing the state of a form at a given point in time. Each change to the form state returns a new state, which maintains the integrity of the model between changes. Reactive forms are built around observable streams, where form inputs and values are provided as streams of input values, which can be accessed synchronously.
+Reactive forms use an explicit and immutable approach to managing the state of a form at a given point in time. Each change to the form state returns a new state, which maintains the integrity of the model between changes. Reactive forms are built around [observable](guide/glossary#observable "Observable definition.") streams, where form inputs and values are provided as streams of input values, which can be accessed synchronously.
 
 Reactive forms also provide a straightforward path to testing because you are assured that your data is consistent and predictable when requested. Any consumers of the streams have access to manipulate that data safely.
 
-Reactive forms differ from template-driven forms in distinct ways. Reactive forms provide more predictability with synchronous access to the data model, immutability with observable operators, and change tracking through observable streams. If you prefer direct access to modify data in your template, template-driven forms are less explicit because they rely on directives embedded in the template, along with mutable data to track changes asynchronously. See the [Forms Overview](guide/forms-overview) for detailed comparisons between the two paradigms.
+Reactive forms differ from [template-driven forms](guide/forms "Template-driven forms guide") in distinct ways. Reactive forms provide more predictability with synchronous access to the data model, immutability with observable operators, and change tracking through observable streams.
 
-## Getting started
+Template-driven forms allow direct access to modify data in your template, but are less explicit than reactive forms because they rely on directives embedded in the template, along with mutable data to track changes asynchronously. See the [Forms Overview](guide/forms-overview "Overview of Angular forms.") for detailed comparisons between the two paradigms.
 
-This section describes how to add a single form control. In the example, the user enters their name into an input field, captures that input value, and displays the current value of the form control element.
+## Adding a basic form control
 
-### Step 1: Registering the reactive forms module
+There are three steps to using form controls.
 
-To use reactive forms, import `ReactiveFormsModule` from the `@angular/forms` package and add it to your NgModule's `imports` array.
+1. Register the reactive forms module in your app. This module declares the reactive-form directives that you need to use reactive forms.
+2. Generate a new `FormControl` instance and save it in the component.
+3. Register the `FormControl` in the template.
+
+You can then display the form by adding the component to the template.
+
+The following examples show how to add a single form control. In the example, the user enters their name into an input field, captures that input value, and displays the current value of the form control element.
+
+**Register the reactive forms module**
+
+To use reactive form controls, import `ReactiveFormsModule` from the `@angular/forms` package and add it to your NgModule's `imports` array.
 
 <code-example path="reactive-forms/src/app/app.module.ts" region="imports" header="src/app/app.module.ts (excerpt)"></code-example>
 
-### Step 2: Generating and importing a new form control
+**Generate a new `FormControl`**
 
-Generate a component for the control.
+Use the [CLI command](cli "Using the Angular command-line interface.") `ng generate` to generate a component in your project to host the control.
 
 <code-example language="sh" class="code-shell">
 
@@ -38,27 +56,29 @@ Generate a component for the control.
 
 </code-example>
 
-The `FormControl` class is the basic building block when using reactive forms. To register a single form control, import the `FormControl` class into your component and create a new instance of the form control to save as a class property.
+To register a single form control, import the `FormControl` class and create a new instance of `FormControl` to save as a class property.
 
 <code-example path="reactive-forms/src/app/name-editor/name-editor.component.ts" region="create-control" header="src/app/name-editor/name-editor.component.ts"></code-example>
 
 Use the constructor of `FormControl` to set its initial value, which in this case is an empty string. By creating these controls in your component class, you get immediate access to listen for, update, and validate the state of the form input.
 
-### Step 3: Registering the control in the template
+**Register the control in the template**
 
-After you create the control in the component class, you must associate it with a form control element in the template. Update the template with the form control using the `formControl` binding provided by `FormControlDirective` included in `ReactiveFormsModule`.
+After you create the control in the component class, you must associate it with a form control element in the template. Update the template with the form control using the `formControl` binding provided by `FormControlDirective`, which is also included in the `ReactiveFormsModule`.
 
 <code-example path="reactive-forms/src/app/name-editor/name-editor.component.html" region="control-binding" header="src/app/name-editor/name-editor.component.html"></code-example>
 
 <div class="alert is-helpful">
 
-**Note:** For a more detailed list of classes and directives provided by `ReactiveFormsModule`, see the [Reactive forms API](#reactive-forms-api) section.
+* For a summary of the classes and directives provided by `ReactiveFormsModule`, see the [Reactive forms API](#reactive-forms-api "API summary.") section below.
+
+* For complete syntax details of these classes and directives, see the API reference documentation for the [Forms package](api/forms "API reference.").
 
 </div>
 
 Using the template binding syntax, the form control is now registered to the `name` input element in the template. The form control and DOM element communicate with each other: the view reflects changes in the model, and the model reflects changes in the view.
 
-#### Displaying the component
+**Display the component**
 
 The form control assigned to `name` is displayed when the component is added to a template.
 
@@ -68,18 +88,14 @@ The form control assigned to `name` is displayed when the component is added to
   <img src="generated/images/guide/reactive-forms/name-editor-1.png" alt="Name Editor">
 </div>
 
-## Managing control values
-
-Reactive forms give you access to the form control state and value at a point in time. You can manipulate
-the current state and value through the component class or the component template. The following examples display the value of the form control instance and change it.
-
 {@a display-value}
 
 ### Displaying a form control value
 
-You can display the value in these ways:
+You can display the value in the following ways.
 
 * Through the `valueChanges` observable where you can listen for changes in the form's value in the template using `AsyncPipe` or in the component class using the `subscribe()` method.
+
 * With the `value` property, which gives you a snapshot of the current value.
 
 The following example shows you how to display the current value using interpolation in the template.
@@ -88,9 +104,10 @@ The following example shows you how to display the current value using interpola
 
 The displayed value changes as you update the form control element.
 
-Reactive forms provide access to information about a given control through properties and methods provided with each instance. These properties and methods of the underlying [AbstractControl](api/forms/AbstractControl) class are used to control form state and determine when to display messages when handling validation. For more information, see [Simple form validation](#simple-form-validation) later in this guide.
+Reactive forms provide access to information about a given control through properties and methods provided with each instance.
+These properties and methods of the underlying [AbstractControl](api/forms/AbstractControl "API reference.") class are used to control form state and determine when to display messages when handling [input validation](#basic-form-validation "Learn more about validating form input.").
 
-Read about other `FormControl` properties and methods in the [Reactive forms API](#reactive-forms-api) section.
+Read about other `FormControl` properties and methods in the [API Reference](api/forms/FormControl "Detailed syntax reference.").
 
 ### Replacing a form control value
 
@@ -114,12 +131,17 @@ The form model is the source of truth for the control, so when you click the but
 
 <div class="alert is-helpful">
 
-**Note:** In this example, you're using a single control. When using the `setValue()` method with a form group or form array instance, the value needs to match the structure of the group or array.
+**Note:** In this example, you're using a single control. When using the `setValue()` method with a [form group](#grouping-form-controls "Learn more about form groups.") or [form array](#creating-dynamic-forms "Learn more about dynamic forms.") instance, the value needs to match the structure of the group or array.
 
 </div>
 
 ## Grouping form controls
 
+Forms typically contain several related controls. Reactive forms provide two ways of grouping multiple related controls into a single input form.
+
+* A form *group* defines a form with a fixed set of controls that you can manage together. Form group basics are discussed in this section. You can also [nest form groups](#nested-groups "See more about nesting groups.") to create more complex forms.
+* A form *array* defines a dynamic form, where you can add and remove controls at run time. You can also nest form arrays to create more complex forms. For more about this option, see [Creating dynamic forms](#dynamic-forms "See more about form arrays.") below.
+
 Just as a form control instance gives you control over a single input field, a form group instance tracks the form state of a group of form control instances (for example, a form). Each control in a form group instance is tracked by name when creating the form group. The following example shows how to manage multiple form control instances in a single group.
 
 Generate a `ProfileEditor` component and import the `FormGroup` and `FormControl` classes from the `@angular/forms` package.
@@ -134,7 +156,13 @@ Generate a `ProfileEditor` component and import the `FormGroup` and `FormControl
 
 </code-example>
 
-### Step 1: Creating a FormGroup instance
+To add a form group to this component, take the following steps.
+
+1. Create a `FormGroup` instance.
+2. Associate the `FormGroup` model and view.
+3. Save the form data.
+
+**Create a FormGroup instance**
 
 Create a property in the component class named `profileForm` and set the property to a new form group instance. To initialize the form group, provide the constructor with an object of named keys mapped to their control.
 
@@ -146,7 +174,7 @@ For the profile form, add two form control instances with the names `firstName`
 
 The individual form controls are now collected within a group. A `FormGroup` instance provides its model value as an object reduced from the values of each control in the group. A form group instance has the same properties (such as `value` and `untouched`) and methods (such as `setValue()`) as a form control instance.
 
-### Step 2: Associating the FormGroup model and view
+**Associate the FormGroup model and view**
 
 A form group tracks the status and changes for each of its controls, so if one of the controls changes, the parent control also emits a new status or value change. The model for the group is maintained from its members. After you define the model, you must update the template to reflect the model in the view.
 
@@ -154,7 +182,7 @@ A form group tracks the status and changes for each of its controls, so if one o
 
 Note that just as a form group contains a group of controls, the *profile form* `FormGroup` is bound to the `form` element with the `FormGroup` directive, creating a communication layer between the model and the form containing the inputs. The `formControlName` input provided by the `FormControlName` directive binds each individual input to the form control defined in `FormGroup`. The form controls communicate with their respective elements. They also communicate changes to the form group instance, which provides the source of truth for the model value.
 
-### Saving form data
+**Save form data**
 
 The `ProfileEditor` component accepts input from the user, but in a real scenario you want to capture the form value and make available for further processing outside the component. The `FormGroup` directive listens for the `submit` event emitted by the `form` element and emits an `ngSubmit` event that you can bind to a callback function.
 
@@ -176,11 +204,11 @@ Use a `button` element to add a button to the bottom of the form to trigger the
 
 <div class="alert is-helpful">
 
-**Note:** The button in the snippet above also has a `disabled` binding attached to it to disable the button when `profileForm` is invalid. You aren't performing any validation yet, so the button is always enabled. Simple form validation is covered in the [Simple form validation](#simple-form-validation) section.
+**Note:** The button in the snippet above also has a `disabled` binding attached to it to disable the button when `profileForm` is invalid. You aren't performing any validation yet, so the button is always enabled. Basic form validation is covered in the [Validating form input](#basic-form-validation "Basic form validation.") section.
 
 </div>
 
-#### Displaying the component
+**Display the component**
 
 To display the `ProfileEditor` component that contains the form, add it to a component template.
 
@@ -192,19 +220,30 @@ To display the `ProfileEditor` component that contains the form, add it to a com
   <img src="generated/images/guide/reactive-forms/profile-editor-1.png" alt="Profile Editor">
 </div>
 
-## Creating nested form groups
+{@a nested-groups}
 
-When building complex forms, managing the different areas of information is easier in smaller sections, and some groups of information naturally fall into the same group. Using a nested form group instance allows you to break large forms groups into smaller, more manageable ones.
+### Creating nested form groups
 
-### Step 1: Creating a nested group
+Form groups can accept both individual form control instances and other form group instances as children. This makes composing complex form models easier to maintain and logically group together.
 
-An address is a good example of information that can be grouped together. Form groups can accept both form control and form group instances as children. This makes composing complex form models easier to maintain and logically group together. To create a nested group in `profileForm`, add a nested `address` element to the form group instance.
+When building complex forms, managing the different areas of information is easier in smaller sections. Using a nested form group instance allows you to break large forms groups into smaller, more manageable ones.
+
+To make more complex forms, use the following steps.
+
+1. Create a nested group.
+2. Group the nested form in the template.
+
+Some types of information naturally fall into the same group. A name and address are typical examples of such nested groups, and are used in the following examples.
+
+**Create a nested group**
+
+To create a nested group in `profileForm`, add a nested `address` element to the form group instance.
 
 <code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup" header="src/app/profile-editor/profile-editor.component.ts (nested form group)"></code-example>
 
 In this example, `address group` combines the current `firstName` and `lastName` controls with the new `street`, `city`, `state`, and `zip` controls. Even though the `address` element in the form group is a child of the overall `profileForm` element in the form group, the same rules apply with value and status changes. Changes in status and value from the nested form group propagate to the parent form group, maintaining consistency with the overall model.
 
-### Step 2: Grouping the nested form in the template
+**Group the nested form in the template**
 
 After you update the model in the component class, update the template to connect the form group instance and its input elements.
 
@@ -220,16 +259,14 @@ The `ProfileEditor` form is displayed as one group, but the model is broken down
 
 <div class="alert is-helpful">
 
-**Note:** Display the value for the form group instance in the component template using the `value` property and `JsonPipe`.
+**Tip** Display the value for the form group instance in the component template using the `value` property and `JsonPipe`.
 
 </div>
 
-## Partial model updates
+### Updating parts of the data model
 
 When updating the value for a form group instance that contains multiple controls, you may only want to update parts of the model. This section covers how to update specific parts of a form control data model.
 
-### Patching the model value
-
 There are two ways to update the model value:
 
 * Use the `setValue()` method to set a new value for an individual control. The `setValue()` method strictly adheres to the structure of the form group and replaces the entire value for the control.
@@ -250,13 +287,19 @@ Simulate an update by adding a button to the template to update the user profile
 
 When a user clicks the button, the `profileForm` model is updated with new values for `firstName` and `street`. Notice that `street` is provided in an object inside the `address` property. This is necessary because the `patchValue()` method applies the update against the model structure. `PatchValue()` only updates properties that the form model defines.
 
-## Generating form controls with FormBuilder
+## Using the FormBuilder service to generate controls
 
 Creating form control instances manually can become repetitive when dealing with multiple forms. The `FormBuilder` service provides convenient methods for generating controls.
 
-The following section refactors the `ProfileEditor` component to use the form builder service to create form control and form group instances.
+Use the following steps to take advantage of this service.
 
-### Step 1: Importing the FormBuilder class
+1. Import the `FormBuilder` class.
+2. Inject the `FormBuilder` service.
+3. Generate the form contents.
+
+The following examples show how to refactor the `ProfileEditor` component to use the form builder service to create form control and form group instances.
+
+**Import the FormBuilder class**
 
 Import the `FormBuilder` class from the `@angular/forms` package.
 
@@ -264,7 +307,7 @@ Import the `FormBuilder` class from the `@angular/forms` package.
 
 </code-example>
 
-### Step 2: Injecting the FormBuilder service
+**Inject the FormBuilder service**
 
 The `FormBuilder` service is an injectable provider that is provided with the reactive forms module. Inject this dependency by adding it to the component constructor.
 
@@ -272,7 +315,7 @@ The `FormBuilder` service is an injectable provider that is provided with the re
 
 </code-example>
 
-### Step 3: Generating form controls
+**Generate form controls**
 
 The `FormBuilder` service has three methods: `control()`, `group()`, and `array()`. These are factory methods for generating instances in your component classes including form controls, form groups, and form arrays.
 
@@ -286,7 +329,7 @@ In the example above, you use the `group()` method with the same object to defin
 
 <div class="alert is-helpful">
 
-**Note:** You can define the control with just the initial value, but if your controls need sync or async validation, add sync and async validators as the second and third items in the array.
+**Tip** You can define the control with just the initial value, but if your controls need sync or async validation, add sync and async validators as the second and third items in the array.
 
 </div>
 
@@ -304,11 +347,21 @@ Compare using the form builder to creating the instances manually.
 
 </code-tabs>
 
-## Simple form validation
+{@a basic-form-validation}
 
-_Form validation_ is used to validate user input to ensure it's complete and correct. This section covers adding a single validator to a form control and displaying the overall form status. Form validation is covered more extensively in the [Form Validation](guide/form-validation) guide.
+## Validating form input
 
-### Step 1: Importing a validator function
+_Form validation_ is used to ensure that user input is complete and correct. This section covers adding a single validator to a form control and displaying the overall form status. Form validation is covered more extensively in the [Form Validation](guide/form-validation "All about form validation.") guide.
+
+Use the following steps to add form validation.
+
+1. Import a validator function in your form component.
+2. Add the validator to the field in the form.
+3. Add logic to handle the validation status.
+
+The most common validation is making a field required. The following example shows how to add a required validation to the `firstName` control and display the result of validation.
+
+**Import a validator function**
 
 Reactive forms include a set of validator functions for common use cases. These functions receive a control to validate against and return an error object or a null value based on the validation check.
 
@@ -318,9 +371,7 @@ Import the `Validators` class from the `@angular/forms` package.
 
 </code-example>
 
-### Step 2: Making a field required
-
-The most common validation is making a field required. This section describes how to add a required validation to the `firstName` control.
+**Make a field required**
 
 In the `ProfileEditor` component, add the `Validators.required` static method as the second item in the array for the `firstName` control.
 
@@ -338,7 +389,7 @@ HTML5 has a set of built-in attributes that you can use for native validation, i
 
 </div>
 
-### Displaying form status
+**Display form status**
 
 When you add a required field to the form control, its initial status is invalid. This invalid status propagates to the parent form group element, making its status invalid. Access the current status of the form group instance through its `status` property.
 
@@ -352,13 +403,24 @@ Display the current status of `profileForm` using interpolation.
 
 The **Submit** button is disabled because `profileForm` is invalid due to the required `firstName` form control. After you fill out the `firstName` input, the form becomes valid and the **Submit** button is enabled.
 
-For more on form validation, visit the [Form Validation](guide/form-validation) guide.
+For more on form validation, visit the [Form Validation](guide/form-validation "All about form validation.") guide.
 
-## Dynamic controls using form arrays
+{@a dynamic-forms}
 
-`FormArray` is an alternative to `FormGroup` for managing any number of unnamed controls. As with form group instances, you can dynamically insert and remove controls from form array instances, and the form array instance value and validation status is calculated from its child controls. However, you don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance. The following example shows you how to manage an array of *aliases* in `ProfileEditor`.
+## Creating dynamic forms
 
-### Step 1: Importing the FormArray class
+`FormArray` is an alternative to `FormGroup` for managing any number of unnamed controls. As with form group instances, you can dynamically insert and remove controls from form array instances, and the form array instance value and validation status is calculated from its child controls. However, you don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance.
+
+To define a dynamic form, take the following steps.
+
+1. Import the `FormArray` class.
+2. Define a `FormArray` control.
+3. Access the `FormArray` control with a getter method.
+4. Display the form array in a template.
+
+The following example shows you how to manage an array of *aliases* in `ProfileEditor`.
+
+**Import the FormArray class**
 
 Import the `FormArray` class from `@angular/forms` to use for type information. The `FormBuilder` service is ready to create a `FormArray` instance.
 
@@ -366,7 +428,7 @@ Import the `FormArray` class from `@angular/forms` to use for type information.
 
 </code-example>
 
-### Step 2: Defining a FormArray control
+**Define a FormArray control**
 
 You can initialize a form array with any number of controls, from zero to many, by defining them in an array. Add an `aliases` property to the form group instance for `profileForm` to define the form array.
 
@@ -378,7 +440,7 @@ Use the `FormBuilder.array()` method to define the array, and the `FormBuilder.c
 
 The aliases control in the form group instance is now populated with a single control until more controls are added dynamically.
 
-### Step 3: Accessing the FormArray control
+**Access the FormArray control**
 
 A getter provides easy access to the aliases in the form array instance compared to repeating the `profileForm.get()` method to get each instance. The form array instance represents an undefined number of controls in an array. It's convenient to access a control through a getter, and this approach is easy to repeat for additional controls.
 
@@ -394,7 +456,8 @@ Use the getter syntax to create an `aliases` class property to retrieve the alia
 
 </div>
 
-Define a method to dynamically insert an alias control into the alias's form array. The `FormArray.push()` method inserts the control as a new item in the array.
+Define a method to dynamically insert an alias control into the alias's form array.
+The `FormArray.push()` method inserts the control as a new item in the array.
 
 <code-example path="reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias" header="src/app/profile-editor/profile-editor.component.ts (add alias)">
 
@@ -402,7 +465,7 @@ Define a method to dynamically insert an alias control into the alias's form arr
 
 In the template, each control is displayed as a separate input field.
 
-### Step 4: Displaying the form array in the template
+**Display the form array in the template**
 
 To attach the aliases from your form model, you must add it to the template. Similar to the `formGroupName` input provided by `FormGroupNameDirective`, `formArrayName` binds communication from the form array instance to the template with `FormArrayNameDirective`.
 
@@ -418,7 +481,7 @@ The `*ngFor` directive iterates over each form control instance provided by the
 
 Each time a new alias instance is added, the new form array instance is provided its control based on the index. This allows you to track each individual control when calculating the status and value of the root control.
 
-#### Adding an alias
+**Add an alias**
 
 Initially, the form contains one `Alias` field. To add another field, click the **Add Alias** button. You can also validate the array of aliases reported by the form model displayed by `Form Value` at the bottom of the template.
 
@@ -428,15 +491,14 @@ Initially, the form contains one `Alias` field. To add another field, click the
 
 </div>
 
-{@a appendix}
 
-## Appendix
 
 {@a reactive-forms-api}
 
-### Reactive forms API
+## Reactive forms API summary
 
-Listed below are the base classes and services used to create and manage form controls.
+The following table lists the base classes and services used to create and manage reactive form controls.
+For complete syntax details, see the API reference documentation for the [Forms package](api/forms "API reference.").
 
 #### Classes
 
diff --git a/packages/forms/src/directives/reactive_directives/form_control_directive.ts b/packages/forms/src/directives/reactive_directives/form_control_directive.ts
index 28d1957a94..0d9711fc03 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_directive.ts
@@ -30,7 +30,12 @@ export const formControlBinding: any = {
 
 /**
  * @description
- * * Syncs a standalone `FormControl` instance to a form control element.
+ * Synchronizes a standalone `FormControl` instance to a form control element.
+ *
+ * Note that support for using the `ngModel` input property and `ngModelChange` event with reactive
+ * form directives was deprecated in Angular v6 and is scheduled for removal in
+ * a future version of Angular.
+ * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
  *
  * @see [Reactive Forms Guide](guide/reactive-forms)
  * @see `FormControl`
@@ -38,80 +43,10 @@ export const formControlBinding: any = {
  *
  * @usageNotes
  *
- * ### Registering a single form control
- *
- * The following examples shows how to register a standalone control and set its value.
+ * The following example shows how to register a standalone control and set its value.
  *
  * {@example forms/ts/simpleFormControl/simple_form_control_example.ts region='Component'}
  *
- * ### Use with ngModel
- *
- * Support for using the `ngModel` input property and `ngModelChange` event with reactive
- * form directives has been deprecated in Angular v6 and will be removed in a future version
- * of Angular.
- *
- * Now deprecated:
- *
- * ```html
- * <input [formControl]="control" [(ngModel)]="value">
- * ```
- *
- * ```ts
- * this.value = 'some value';
- * ```
- *
- * This has been deprecated for a few reasons. First, developers have found this pattern
- * confusing. It seems like the actual `ngModel` directive is being used, but in fact it's
- * an input/output property named `ngModel` on the reactive form directive that simply
- * approximates (some of) its behavior. Specifically, it allows getting/setting the value
- * and intercepting value events. However, some of `ngModel`'s other features - like
- * delaying updates with`ngModelOptions` or exporting the directive - simply don't work,
- * which has understandably caused some confusion.
- *
- * In addition, this pattern mixes template-driven and reactive forms strategies, which
- * we generally don't recommend because it doesn't take advantage of the full benefits of
- * either strategy. Setting the value in the template violates the template-agnostic
- * principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in
- * the class removes the convenience of defining forms in the template.
- *
- * To update your code before support is removed, you'll want to decide whether to stick
- * with reactive form directives (and get/set values using reactive forms patterns) or
- * switch over to template-driven directives.
- *
- * After (choice 1 - use reactive forms):
- *
- * ```html
- * <input [formControl]="control">
- * ```
- *
- * ```ts
- * this.control.setValue('some value');
- * ```
- *
- * After (choice 2 - use template-driven forms):
- *
- * ```html
- * <input [(ngModel)]="value">
- * ```
- *
- * ```ts
- * this.value = 'some value';
- * ```
- *
- * By default, when you use this pattern, you will see a deprecation warning once in dev
- * mode. You can choose to silence this warning by providing a config for
- * `ReactiveFormsModule` at import time:
- *
- * ```ts
- * imports: [
- *   ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
- * ]
- * ```
- *
- * Alternatively, you can choose to surface a separate warning for each instance of this
- * pattern with a config value of `"always"`. This may help to track down where in the code
- * the pattern is being used as the code is being updated.
- *
  * @ngModule ReactiveFormsModule
  * @publicApi
  */
diff --git a/packages/forms/src/directives/reactive_directives/form_control_name.ts b/packages/forms/src/directives/reactive_directives/form_control_name.ts
index 6a4e9da351..d425f8da5d 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts
@@ -50,77 +50,13 @@ export const controlNameBinding: any = {
  * * Radio buttons: `RadioControlValueAccessor`
  * * Selects: `SelectControlValueAccessor`
  *
- * ### Use with ngModel
+ * ### Use with ngModel is deprecated
  *
  * Support for using the `ngModel` input property and `ngModelChange` event with reactive
- * form directives has been deprecated in Angular v6 and will be removed in a future
- * version of Angular.
+ * form directives has been deprecated in Angular v6 and is scheduled for removal in
+ * a future version of Angular.
  *
- * Now deprecated:
- *
- * ```html
- * <form [formGroup]="form">
- *   <input formControlName="first" [(ngModel)]="value">
- * </form>
- * ```
- *
- * ```ts
- * this.value = 'some value';
- * ```
- *
- * This has been deprecated for a few reasons. First, developers have found this pattern
- * confusing. It seems like the actual `ngModel` directive is being used, but in fact it's
- * an input/output property named `ngModel` on the reactive form directive that simply
- * approximates (some of) its behavior. Specifically, it allows getting/setting the value
- * and intercepting value events. However, some of `ngModel`'s other features - like
- * delaying updates with `ngModelOptions` or exporting the directive - simply don't work,
- * which has understandably caused some confusion.
- *
- * In addition, this pattern mixes template-driven and reactive forms strategies, which
- * we generally don't recommend because it doesn't take advantage of the full benefits of
- * either strategy. Setting the value in the template violates the template-agnostic
- * principles behind reactive forms, whereas adding a `FormControl`/`FormGroup` layer in
- * the class removes the convenience of defining forms in the template.
- *
- * To update your code before support is removed, you'll want to decide whether to stick with
- * reactive form directives (and get/set values using reactive forms patterns) or switch over to
- * template-driven directives.
- *
- * After (choice 1 - use reactive forms):
- *
- * ```html
- * <form [formGroup]="form">
- *   <input formControlName="first">
- * </form>
- * ```
- *
- * ```ts
- * this.form.get('first').setValue('some value');
- * ```
- *
- * After (choice 2 - use template-driven forms):
- *
- * ```html
- * <input [(ngModel)]="value">
- * ```
- *
- * ```ts
- * this.value = 'some value';
- * ```
- *
- * By default, when you use this pattern, you will see a deprecation warning once in dev
- * mode. You can choose to silence this warning by providing a config for
- * `ReactiveFormsModule` at import time:
- *
- * ```ts
- * imports: [
- *   ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'})
- * ]
- * ```
- *
- * Alternatively, you can choose to surface a separate warning for each instance of this
- * pattern with a config value of `"always"`. This may help to track down where in the code
- * the pattern is being used as the code is being updated.
+ * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
  *
  * @ngModule ReactiveFormsModule
  * @publicApi
diff --git a/packages/forms/src/form_providers.ts b/packages/forms/src/form_providers.ts
index 2fdd72b476..5de31a7041 100644
--- a/packages/forms/src/form_providers.ts
+++ b/packages/forms/src/form_providers.ts
@@ -16,7 +16,8 @@ import {FormBuilder} from './form_builder';
  * Exports the required providers and directives for template-driven forms,
  * making them available for import by NgModules that import this module.
  *
- * @see [Forms Guide](/guide/forms)
+ * @see [Forms Overview](/guide/forms-overview)
+ * @see [Template-driven Forms Guide](/guide/forms)
  *
  * @publicApi
  */
@@ -31,9 +32,9 @@ export class FormsModule {
 /**
  * Exports the required infrastructure and directives for reactive forms,
  * making them available for import by NgModules that import this module.
- * @see [Forms](guide/reactive-forms)
  *
- * @see [Reactive Forms Guide](/guide/reactive-forms)
+ * @see [Forms Overview](guide/forms-overview)
+ * @see [Reactive Forms Guide](guide/reactive-forms)
  *
  * @publicApi
  */
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
index 169f9e7446..dc49b05075 100644
--- a/packages/forms/src/model.ts
+++ b/packages/forms/src/model.ts
@@ -700,6 +700,7 @@ export abstract class AbstractControl {
    * Calling `setErrors` also updates the validity of the parent control.
    *
    * @usageNotes
+   *
    * ### Manually set the errors for a control
    *
    * ```
@@ -935,7 +936,7 @@ export abstract class AbstractControl {
  * This is one of the three fundamental building blocks of Angular forms, along with
  * `FormGroup` and `FormArray`. It extends the `AbstractControl` class that
  * implements most of the base functionality for accessing the value, validation status,
- * user interactions and events.
+ * user interactions and events. See [usage examples below](#usage-notes).
  *
  * @see `AbstractControl`
  * @see [Reactive Forms Guide](guide/reactive-forms)