From 4270c7f82416c260544f92a24cffd63799bd6467 Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Thu, 5 Apr 2018 10:40:58 +0100
Subject: [PATCH 1/3] docs(forms): migrate deprecated `@howToUse` tags

In this case they have been converted to `@description` tags.
---
 packages/forms/src/directives/ng_form.ts                    | 2 +-
 packages/forms/src/directives/ng_model.ts                   | 2 +-
 packages/forms/src/directives/ng_model_group.ts             | 2 +-
 .../forms/src/directives/radio_control_value_accessor.ts    | 2 +-
 .../reactive_directives/form_control_directive.ts           | 2 +-
 .../src/directives/reactive_directives/form_control_name.ts | 2 +-
 .../directives/reactive_directives/form_group_directive.ts  | 2 +-
 .../src/directives/reactive_directives/form_group_name.ts   | 4 ++--
 .../forms/src/directives/select_control_value_accessor.ts   | 4 ++--
 packages/forms/src/form_builder.ts                          | 2 +-
 packages/forms/src/model.ts                                 | 6 +++---
 11 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/forms/src/directives/ng_form.ts b/packages/forms/src/directives/ng_form.ts
index 94fc94ef45071..c46b6c6e32657 100644
--- a/packages/forms/src/directives/ng_form.ts
+++ b/packages/forms/src/directives/ng_form.ts
@@ -29,7 +29,7 @@ const resolvedPromise = Promise.resolve(null);
  * @whatItDoes Creates a top-level {@link FormGroup} instance and binds it to a form
  * to track aggregate form value and validation status.
  *
- * @howToUse
+ * @description
  *
  * As soon as you import the `FormsModule`, this directive becomes active by default on
  * all `<form>` tags.  You don't need to add a special selector.
diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts
index f98d68b1a8c44..a0457bc6bf891 100644
--- a/packages/forms/src/directives/ng_model.ts
+++ b/packages/forms/src/directives/ng_model.ts
@@ -54,7 +54,7 @@ const resolvedPromise = Promise.resolve(null);
  * within a parent form, the directive will also register itself with the form as a child
  * control.
  *
- * @howToUse
+ * @description
  *
  * This directive can be used by itself or as part of a larger form. All you need is the
  * `ngModel` selector to activate it.
diff --git a/packages/forms/src/directives/ng_model_group.ts b/packages/forms/src/directives/ng_model_group.ts
index f463c3ec78704..b260f8ce04866 100644
--- a/packages/forms/src/directives/ng_model_group.ts
+++ b/packages/forms/src/directives/ng_model_group.ts
@@ -23,7 +23,7 @@ export const modelGroupProvider: any = {
 /**
  * @whatItDoes Creates and binds a {@link FormGroup} instance to a DOM element.
  *
- * @howToUse
+ * @description
  *
  * This directive can only be used as a child of {@link NgForm} (or in other words,
  * within `<form>` tags).
diff --git a/packages/forms/src/directives/radio_control_value_accessor.ts b/packages/forms/src/directives/radio_control_value_accessor.ts
index 75af9de4aaf48..f322723e0f5b4 100644
--- a/packages/forms/src/directives/radio_control_value_accessor.ts
+++ b/packages/forms/src/directives/radio_control_value_accessor.ts
@@ -60,7 +60,7 @@ export class RadioControlRegistry {
  * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
  * to keep the view synced with the {@link FormControl} model.
  *
- * @howToUse
+ * @description
  *
  * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
  * value accessor will be active on any radio control that has a form directive. You do
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 8f36a785ad3c7..80f50510568cb 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_directive.ts
@@ -36,7 +36,7 @@ export const formControlBinding: any = {
  * any values written to the DOM element through user input will be reflected in the
  * {@link FormControl} instance (view -> model).
  *
- * @howToUse
+ * @description
  *
  * Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
  * Simply create a {@link FormControl}, save it to your component class, and pass it into the
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 04747e608fc6d..1e2f833c411d1 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts
@@ -36,7 +36,7 @@ export const controlNameBinding: any = {
  * any values written to the DOM element through user input will be reflected in the
  * {@link FormControl} instance (view -> model).
  *
- * @howToUse
+ * @description
  *
  * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
diff --git a/packages/forms/src/directives/reactive_directives/form_group_directive.ts b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
index f172bcab77315..0aa86ed8e5995 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
@@ -25,7 +25,7 @@ export const formDirectiveProvider: any = {
 /**
  * @whatItDoes Binds an existing {@link FormGroup} to a DOM element.
  *
- * @howToUse
+ * @description
  *
  * This directive accepts an existing {@link FormGroup} instance. It will then use this
  * {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup},
diff --git a/packages/forms/src/directives/reactive_directives/form_group_name.ts b/packages/forms/src/directives/reactive_directives/form_group_name.ts
index 68434d1b0b683..02903d609d392 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_name.ts
@@ -26,7 +26,7 @@ export const formGroupNameProvider: any = {
 /**
  * @whatItDoes Syncs a nested {@link FormGroup} to a DOM element.
  *
- * @howToUse
+ * @description
  *
  * This directive can only be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
@@ -97,7 +97,7 @@ export const formArrayNameProvider: any = {
 /**
  * @whatItDoes Syncs a nested {@link FormArray} to a DOM element.
  *
- * @howToUse
+ * @description
  *
  * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
diff --git a/packages/forms/src/directives/select_control_value_accessor.ts b/packages/forms/src/directives/select_control_value_accessor.ts
index 127470237b8ac..363d4d319dbe0 100644
--- a/packages/forms/src/directives/select_control_value_accessor.ts
+++ b/packages/forms/src/directives/select_control_value_accessor.ts
@@ -32,7 +32,7 @@ function _extractId(valueString: string): string {
  * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
  * to keep the view synced with the {@link FormControl} model.
  *
- * @howToUse
+ * @description
  *
  * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
  * value accessor will be active on any select control that has a form directive. You do
@@ -160,7 +160,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
 /**
  * @whatItDoes Marks `<option>` as dynamic, so Angular can be notified when options change.
  *
- * @howToUse
+ * @description
  *
  * See docs for {@link SelectControlValueAccessor} for usage examples.
  *
diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts
index 1d5f8a220198c..fe845b07f452d 100644
--- a/packages/forms/src/form_builder.ts
+++ b/packages/forms/src/form_builder.ts
@@ -18,7 +18,7 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
  * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
  * forms.
  *
- * @howToUse
+ * @description
  *
  * To use, inject `FormBuilder` into your component class. You can then call its methods
  * directly.
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
index 13f2808a957f0..16431d811edde 100644
--- a/packages/forms/src/model.ts
+++ b/packages/forms/src/model.ts
@@ -673,7 +673,7 @@ export abstract class AbstractControl {
  * It is one of the three fundamental building blocks of Angular forms, along with
  * {@link FormGroup} and {@link FormArray}.
  *
- * @howToUse
+ * @description
  *
  * When instantiating a {@link FormControl}, you can pass in an initial value as the
  * first argument. Example:
@@ -917,7 +917,7 @@ export class FormControl extends AbstractControl {
  * `FormGroup` is one of the three fundamental building blocks used to define forms in Angular,
  * along with {@link FormControl} and {@link FormArray}.
  *
- * @howToUse
+ * @description
  *
  * When instantiating a {@link FormGroup}, pass in a collection of child controls as the first
  * argument. The key for each child will be the name under which it is registered.
@@ -1260,7 +1260,7 @@ export class FormGroup extends AbstractControl {
  * `FormArray` is one of the three fundamental building blocks used to define forms in Angular,
  * along with {@link FormControl} and {@link FormGroup}.
  *
- * @howToUse
+ * @description
  *
  * When instantiating a {@link FormArray}, pass in an array of child controls as the first
  * argument.

From abe773ef40254128cd62017c0f59e7a12a9646da Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Thu, 5 Apr 2018 11:02:42 +0100
Subject: [PATCH 2/3] docs(forms): migrate `@whatItDoes` tags to the
 description

We get the overview for the doc by splitting off the first
paragraph.
---
 packages/forms/src/directives/ng_form.ts      |  6 ++--
 packages/forms/src/directives/ng_model.ts     |  6 ++--
 .../forms/src/directives/ng_model_group.ts    |  4 +--
 .../directives/ng_no_validate_directive.ts    |  4 ++-
 .../radio_control_value_accessor.ts           |  6 ++--
 .../form_control_directive.ts                 |  8 ++---
 .../reactive_directives/form_control_name.ts  |  8 ++---
 .../form_group_directive.ts                   |  4 +--
 .../reactive_directives/form_group_name.ts    |  8 ++---
 .../select_control_value_accessor.ts          | 10 +++----
 packages/forms/src/form_builder.ts            |  8 ++---
 packages/forms/src/model.ts                   | 30 ++++++++++---------
 12 files changed, 53 insertions(+), 49 deletions(-)

diff --git a/packages/forms/src/directives/ng_form.ts b/packages/forms/src/directives/ng_form.ts
index c46b6c6e32657..5ab061eb0c198 100644
--- a/packages/forms/src/directives/ng_form.ts
+++ b/packages/forms/src/directives/ng_form.ts
@@ -26,11 +26,11 @@ export const formDirectiveProvider: any = {
 const resolvedPromise = Promise.resolve(null);
 
 /**
- * @whatItDoes Creates a top-level {@link FormGroup} instance and binds it to a form
- * to track aggregate form value and validation status.
- *
  * @description
  *
+ * Creates a top-level {@link FormGroup} instance and binds it to a form
+ * to track aggregate form value and validation status.
+ *
  * As soon as you import the `FormsModule`, this directive becomes active by default on
  * all `<form>` tags.  You don't need to add a special selector.
  *
diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts
index a0457bc6bf891..f4164f2360e95 100644
--- a/packages/forms/src/directives/ng_model.ts
+++ b/packages/forms/src/directives/ng_model.ts
@@ -46,7 +46,9 @@ export const formControlBinding: any = {
 const resolvedPromise = Promise.resolve(null);
 
 /**
- * @whatItDoes Creates a {@link FormControl} instance from a domain model and binds it
+ * @description
+ *
+ * Creates a {@link FormControl} instance from a domain model and binds it
  * to a form control element.
  *
  * The {@link FormControl} instance will track the value, user interaction, and
@@ -54,8 +56,6 @@ const resolvedPromise = Promise.resolve(null);
  * within a parent form, the directive will also register itself with the form as a child
  * control.
  *
- * @description
- *
  * This directive can be used by itself or as part of a larger form. All you need is the
  * `ngModel` selector to activate it.
  *
diff --git a/packages/forms/src/directives/ng_model_group.ts b/packages/forms/src/directives/ng_model_group.ts
index b260f8ce04866..4da5587e39941 100644
--- a/packages/forms/src/directives/ng_model_group.ts
+++ b/packages/forms/src/directives/ng_model_group.ts
@@ -21,10 +21,10 @@ export const modelGroupProvider: any = {
 };
 
 /**
- * @whatItDoes Creates and binds a {@link FormGroup} instance to a DOM element.
- *
  * @description
  *
+ * Creates and binds a {@link FormGroup} instance to a DOM element.
+ *
  * This directive can only be used as a child of {@link NgForm} (or in other words,
  * within `<form>` tags).
  *
diff --git a/packages/forms/src/directives/ng_no_validate_directive.ts b/packages/forms/src/directives/ng_no_validate_directive.ts
index 7bcdf6fbbe717..b20f07a95c444 100644
--- a/packages/forms/src/directives/ng_no_validate_directive.ts
+++ b/packages/forms/src/directives/ng_no_validate_directive.ts
@@ -9,7 +9,9 @@
 import {Directive} from '@angular/core';
 
 /**
- * @whatItDoes Adds `novalidate` attribute to all forms by default.
+ * @description
+ *
+ * Adds `novalidate` attribute to all forms by default.
  *
  * `novalidate` is used to disable browser's native form validation.
  *
diff --git a/packages/forms/src/directives/radio_control_value_accessor.ts b/packages/forms/src/directives/radio_control_value_accessor.ts
index f322723e0f5b4..7637100ea600c 100644
--- a/packages/forms/src/directives/radio_control_value_accessor.ts
+++ b/packages/forms/src/directives/radio_control_value_accessor.ts
@@ -55,13 +55,13 @@ export class RadioControlRegistry {
 }
 
 /**
- * @whatItDoes  Writes radio control values and listens to radio control changes.
+ * @description
+ *
+ * Writes radio control values and listens to radio control changes.
  *
  * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
  * to keep the view synced with the {@link FormControl} model.
  *
- * @description
- *
  * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
  * value accessor will be active on any radio control that has a form directive. You do
  * **not** need to add a special selector to activate it.
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 80f50510568cb..1da0c3e9cee1c 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_directive.ts
@@ -29,15 +29,15 @@ export const formControlBinding: any = {
 };
 
 /**
- * @whatItDoes Syncs a standalone {@link FormControl} instance to a form control element.
+ * @description
+ *
+ * Syncs a standalone {@link FormControl} instance to a form control element.
  *
- * In other words, this directive ensures that any values written to the {@link FormControl}
+ * This directive ensures that any values written to the {@link FormControl}
  * instance programmatically will be written to the DOM element (model -> view). Conversely,
  * any values written to the DOM element through user input will be reflected in the
  * {@link FormControl} instance (view -> model).
  *
- * @description
- *
  * Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
  * Simply create a {@link FormControl}, save it to your component class, and pass it into the
  * {@link FormControlDirective}.
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 1e2f833c411d1..05d0328eaede9 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts
@@ -28,16 +28,16 @@ export const controlNameBinding: any = {
 };
 
 /**
- * @whatItDoes  Syncs a {@link FormControl} in an existing {@link FormGroup} to a form control
+ * @description
+ *
+ * Syncs a {@link FormControl} in an existing {@link FormGroup} to a form control
  * element by name.
  *
- * In other words, this directive ensures that any values written to the {@link FormControl}
+ * This directive ensures that any values written to the {@link FormControl}
  * instance programmatically will be written to the DOM element (model -> view). Conversely,
  * any values written to the DOM element through user input will be reflected in the
  * {@link FormControl} instance (view -> model).
  *
- * @description
- *
  * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
  *
diff --git a/packages/forms/src/directives/reactive_directives/form_group_directive.ts b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
index 0aa86ed8e5995..eb5be54f25db0 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
@@ -23,10 +23,10 @@ export const formDirectiveProvider: any = {
 };
 
 /**
- * @whatItDoes Binds an existing {@link FormGroup} to a DOM element.
- *
  * @description
  *
+ * Binds an existing {@link FormGroup} to a DOM element.
+ *
  * This directive accepts an existing {@link FormGroup} instance. It will then use this
  * {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup},
  * and {@link FormArray} instances to child {@link FormControlName}, {@link FormGroupName},
diff --git a/packages/forms/src/directives/reactive_directives/form_group_name.ts b/packages/forms/src/directives/reactive_directives/form_group_name.ts
index 02903d609d392..e3c1242a45389 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_name.ts
@@ -24,10 +24,10 @@ export const formGroupNameProvider: any = {
 };
 
 /**
- * @whatItDoes Syncs a nested {@link FormGroup} to a DOM element.
- *
  * @description
  *
+ * Syncs a nested {@link FormGroup} to a DOM element.
+ *
  * This directive can only be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
  *
@@ -95,10 +95,10 @@ export const formArrayNameProvider: any = {
 };
 
 /**
- * @whatItDoes Syncs a nested {@link FormArray} to a DOM element.
- *
  * @description
  *
+ * Syncs a nested {@link FormArray} to a DOM element.
+ *
  * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
  * `[formGroup]`).
  *
diff --git a/packages/forms/src/directives/select_control_value_accessor.ts b/packages/forms/src/directives/select_control_value_accessor.ts
index 363d4d319dbe0..919efcbad2408 100644
--- a/packages/forms/src/directives/select_control_value_accessor.ts
+++ b/packages/forms/src/directives/select_control_value_accessor.ts
@@ -27,13 +27,13 @@ function _extractId(valueString: string): string {
 }
 
 /**
- * @whatItDoes Writes values and listens to changes on a select element.
+ * @description
+ *
+ * Writes values and listens to changes on a select element.
  *
  * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
  * to keep the view synced with the {@link FormControl} model.
  *
- * @description
- *
  * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
  * value accessor will be active on any select control that has a form directive. You do
  * **not** need to add a special selector to activate it.
@@ -158,10 +158,10 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
 }
 
 /**
- * @whatItDoes Marks `<option>` as dynamic, so Angular can be notified when options change.
- *
  * @description
  *
+ * Marks `<option>` as dynamic, so Angular can be notified when options change.
+ *
  * See docs for {@link SelectControlValueAccessor} for usage examples.
  *
  * @stable
diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts
index fe845b07f452d..2587537a5394e 100644
--- a/packages/forms/src/form_builder.ts
+++ b/packages/forms/src/form_builder.ts
@@ -12,14 +12,14 @@ import {AsyncValidatorFn, ValidatorFn} from './directives/validators';
 import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
 
 /**
- * @whatItDoes Creates an {@link AbstractControl} from a user-specified configuration.
+ * @description
+ *
+ * Creates an {@link AbstractControl} from a user-specified configuration.
  *
- * It is essentially syntactic sugar that shortens the `new FormGroup()`,
+ * This is essentially syntactic sugar that shortens the `new FormGroup()`,
  * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
  * forms.
  *
- * @description
- *
  * To use, inject `FormBuilder` into your component class. You can then call its methods
  * directly.
  *
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
index 16431d811edde..1772a05dcc679 100644
--- a/packages/forms/src/model.ts
+++ b/packages/forms/src/model.ts
@@ -81,7 +81,9 @@ function coerceToAsyncValidator(
 export type FormHooks = 'change' | 'blur' | 'submit';
 
 /**
- * @whatItDoes Interface for options provided to an {@link AbstractControl}.
+ * @description
+ *
+ * Interface for options provided to an {@link AbstractControl}.
  *
  * @experimental
  */
@@ -109,8 +111,9 @@ function isOptionsObj(
 
 
 /**
- * @whatItDoes This is the base class for {@link FormControl}, {@link FormGroup}, and
- * {@link FormArray}.
+ * @description
+ *
+ * This is the base class for {@link FormControl}, {@link FormGroup}, and {@link FormArray}.
  *
  * It provides some of the shared behavior that all controls and groups of controls have, like
  * running validators, calculating status, and resetting state. It also defines the properties
@@ -668,12 +671,12 @@ export abstract class AbstractControl {
 }
 
 /**
- * @whatItDoes Tracks the value and validation status of an individual form control.
+ * @description
  *
- * It is one of the three fundamental building blocks of Angular forms, along with
- * {@link FormGroup} and {@link FormArray}.
+ * Tracks the value and validation status of an individual form control.
  *
- * @description
+ * This is one of the three fundamental building blocks of Angular forms, along with
+ * {@link FormGroup} and {@link FormArray}.
  *
  * When instantiating a {@link FormControl}, you can pass in an initial value as the
  * first argument. Example:
@@ -906,8 +909,9 @@ export class FormControl extends AbstractControl {
 }
 
 /**
- * @whatItDoes Tracks the value and validity state of a group of {@link FormControl}
- * instances.
+ * @description
+ *
+ * Tracks the value and validity state of a group of {@link FormControl} instances.
  *
  * A `FormGroup` aggregates the values of each child {@link FormControl} into one object,
  * with each control name as the key.  It calculates its status by reducing the statuses
@@ -917,8 +921,6 @@ export class FormControl extends AbstractControl {
  * `FormGroup` is one of the three fundamental building blocks used to define forms in Angular,
  * along with {@link FormControl} and {@link FormArray}.
  *
- * @description
- *
  * When instantiating a {@link FormGroup}, pass in a collection of child controls as the first
  * argument. The key for each child will be the name under which it is registered.
  *
@@ -1250,7 +1252,9 @@ export class FormGroup extends AbstractControl {
 }
 
 /**
- * @whatItDoes Tracks the value and validity state of an array of {@link FormControl},
+ * @description
+ *
+ * Tracks the value and validity state of an array of {@link FormControl},
  * {@link FormGroup} or {@link FormArray} instances.
  *
  * A `FormArray` aggregates the values of each child {@link FormControl} into an array.
@@ -1260,8 +1264,6 @@ export class FormGroup extends AbstractControl {
  * `FormArray` is one of the three fundamental building blocks used to define forms in Angular,
  * along with {@link FormControl} and {@link FormGroup}.
  *
- * @description
- *
  * When instantiating a {@link FormArray}, pass in an array of child controls as the first
  * argument.
  *

From dc5e9f0cf20781995abd97dd52be679f358801e3 Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Thu, 5 Apr 2018 10:58:12 +0100
Subject: [PATCH 3/3] docs(forms): remove unnecessary `{@link Injector}` jsdoc
 tags

Inline code blocks are automatically linked, if possible, to their API
page.
---
 .../directives/abstract_control_directive.ts  |  4 +-
 .../abstract_form_group_directive.ts          |  6 +--
 .../forms/src/directives/control_container.ts |  2 +-
 .../src/directives/control_value_accessor.ts  |  4 +-
 .../src/directives/default_value_accessor.ts  |  2 +-
 .../forms/src/directives/form_interface.ts    |  6 +--
 packages/forms/src/directives/ng_control.ts   |  2 +-
 packages/forms/src/directives/ng_form.ts      |  8 +--
 packages/forms/src/directives/ng_model.ts     | 14 ++---
 .../forms/src/directives/ng_model_group.ts    |  4 +-
 .../src/directives/number_value_accessor.ts   |  2 +-
 .../radio_control_value_accessor.ts           |  6 +--
 .../src/directives/range_value_accessor.ts    |  2 +-
 .../form_control_directive.ts                 | 24 ++++-----
 .../reactive_directives/form_control_name.ts  | 28 +++++-----
 .../form_group_directive.ts                   | 16 +++---
 .../reactive_directives/form_group_name.ts    | 40 +++++++-------
 .../select_control_value_accessor.ts          |  8 +--
 packages/forms/src/directives/validators.ts   | 18 +++----
 packages/forms/src/form_builder.ts            | 12 ++---
 packages/forms/src/forms.ts                   |  4 +-
 packages/forms/src/model.ts                   | 52 +++++++++----------
 packages/forms/src/validators.ts              |  8 +--
 23 files changed, 136 insertions(+), 136 deletions(-)

diff --git a/packages/forms/src/directives/abstract_control_directive.ts b/packages/forms/src/directives/abstract_control_directive.ts
index af3da025e00d8..b63132ba14053 100644
--- a/packages/forms/src/directives/abstract_control_directive.ts
+++ b/packages/forms/src/directives/abstract_control_directive.ts
@@ -19,7 +19,7 @@ import {ValidationErrors} from './validators';
  */
 export abstract class AbstractControlDirective {
   /**
-   * The {@link FormControl}, {@link FormGroup}, or {@link FormArray}
+   * The `FormControl`, `FormGroup`, or `FormArray`
    * that backs this directive. Most properties fall through to that
    * instance.
    */
@@ -137,7 +137,7 @@ export abstract class AbstractControlDirective {
    * * it is marked as `untouched`
    * * value is set to null
    *
-   * For more information, see {@link AbstractControl}.
+   * For more information, see `AbstractControl`.
    */
   reset(value: any = undefined): void {
     if (this.control) this.control.reset(value);
diff --git a/packages/forms/src/directives/abstract_form_group_directive.ts b/packages/forms/src/directives/abstract_form_group_directive.ts
index 30829df9f20e7..df3df50e2b428 100644
--- a/packages/forms/src/directives/abstract_form_group_directive.ts
+++ b/packages/forms/src/directives/abstract_form_group_directive.ts
@@ -18,7 +18,7 @@ import {AsyncValidatorFn, ValidatorFn} from './validators';
 
 
 /**
- * This is a base class for code shared between {@link NgModelGroup} and {@link FormGroupName}.
+ * This is a base class for code shared between `NgModelGroup` and `FormGroupName`.
  *
  * @stable
  */
@@ -44,7 +44,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
   }
 
   /**
-   * Get the {@link FormGroup} backing this binding.
+   * Get the `FormGroup` backing this binding.
    */
   get control(): FormGroup { return this.formDirective !.getFormGroup(this); }
 
@@ -54,7 +54,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
   get path(): string[] { return controlPath(this.name, this._parent); }
 
   /**
-   * Get the {@link Form} to which this group belongs.
+   * Get the `Form` to which this group belongs.
    */
   get formDirective(): Form|null { return this._parent ? this._parent.formDirective : null; }
 
diff --git a/packages/forms/src/directives/control_container.ts b/packages/forms/src/directives/control_container.ts
index 39225c0dcad7c..305d6aeeace87 100644
--- a/packages/forms/src/directives/control_container.ts
+++ b/packages/forms/src/directives/control_container.ts
@@ -11,7 +11,7 @@ import {Form} from './form_interface';
 
 
 /**
- * A directive that contains multiple {@link NgControl}s.
+ * A directive that contains multiple `NgControl`s.
  *
  * Only used by the forms module.
  *
diff --git a/packages/forms/src/directives/control_value_accessor.ts b/packages/forms/src/directives/control_value_accessor.ts
index ace1f1b2f2688..6c65d9ff04c11 100644
--- a/packages/forms/src/directives/control_value_accessor.ts
+++ b/packages/forms/src/directives/control_value_accessor.ts
@@ -110,9 +110,9 @@ export interface ControlValueAccessor {
 }
 
 /**
- * Used to provide a {@link ControlValueAccessor} for form controls.
+ * Used to provide a `ControlValueAccessor` for form controls.
  *
- * See {@link DefaultValueAccessor} for how to implement one.
+ * See `DefaultValueAccessor` for how to implement one.
  * @stable
  */
 export const NG_VALUE_ACCESSOR = new InjectionToken<ControlValueAccessor>('NgValueAccessor');
diff --git a/packages/forms/src/directives/default_value_accessor.ts b/packages/forms/src/directives/default_value_accessor.ts
index 3120f372c610b..2758a879fae35 100644
--- a/packages/forms/src/directives/default_value_accessor.ts
+++ b/packages/forms/src/directives/default_value_accessor.ts
@@ -33,7 +33,7 @@ export const COMPOSITION_BUFFER_MODE = new InjectionToken<boolean>('CompositionE
 
 /**
  * The default accessor for writing a value and listening to changes that is used by the
- * {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
+ * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
  *  ### Example
  *  ```
diff --git a/packages/forms/src/directives/form_interface.ts b/packages/forms/src/directives/form_interface.ts
index c425bfb951b07..ca7e96d666d30 100644
--- a/packages/forms/src/directives/form_interface.ts
+++ b/packages/forms/src/directives/form_interface.ts
@@ -14,7 +14,7 @@ import {NgControl} from './ng_control';
 
 
 /**
- * An interface that {@link FormGroupDirective} and {@link NgForm} implement.
+ * An interface that `FormGroupDirective` and `NgForm` implement.
  *
  * Only used by the forms module.
  *
@@ -32,7 +32,7 @@ export interface Form {
   removeControl(dir: NgControl): void;
 
   /**
-   * Look up the {@link FormControl} associated with a particular {@link NgControl}.
+   * Look up the `FormControl` associated with a particular `NgControl`.
    */
   getControl(dir: NgControl): FormControl;
 
@@ -47,7 +47,7 @@ export interface Form {
   removeFormGroup(dir: AbstractFormGroupDirective): void;
 
   /**
-   * Look up the {@link FormGroup} associated with a particular {@link AbstractFormGroupDirective}.
+   * Look up the `FormGroup` associated with a particular `AbstractFormGroupDirective`.
    */
   getFormGroup(dir: AbstractFormGroupDirective): FormGroup;
 
diff --git a/packages/forms/src/directives/ng_control.ts b/packages/forms/src/directives/ng_control.ts
index 503adf928197c..00f4b59aebf53 100644
--- a/packages/forms/src/directives/ng_control.ts
+++ b/packages/forms/src/directives/ng_control.ts
@@ -18,7 +18,7 @@ function unimplemented(): any {
 
 /**
  * A base class that all control directive extend.
- * It binds a {@link FormControl} object to a DOM element.
+ * It binds a `FormControl` object to a DOM element.
  *
  * Used internally by Angular forms.
  *
diff --git a/packages/forms/src/directives/ng_form.ts b/packages/forms/src/directives/ng_form.ts
index 5ab061eb0c198..b9256ba1d9c5b 100644
--- a/packages/forms/src/directives/ng_form.ts
+++ b/packages/forms/src/directives/ng_form.ts
@@ -28,7 +28,7 @@ const resolvedPromise = Promise.resolve(null);
 /**
  * @description
  *
- * Creates a top-level {@link FormGroup} instance and binds it to a form
+ * Creates a top-level `FormGroup` instance and binds it to a form
  * to track aggregate form value and validation status.
  *
  * As soon as you import the `FormsModule`, this directive becomes active by default on
@@ -36,12 +36,12 @@ const resolvedPromise = Promise.resolve(null);
  *
  * You can export the directive into a local template variable using `ngForm` as the key
  * (ex: `#myForm="ngForm"`). This is optional, but useful.  Many properties from the underlying
- * {@link FormGroup} instance are duplicated on the directive itself, so a reference to it
+ * `FormGroup` instance are duplicated on the directive itself, so a reference to it
  * will give you access to the aggregate value and validity status of the form, as well as
  * user interaction properties like `dirty` and `touched`.
  *
- * To register child controls with the form, you'll want to use {@link NgModel} with a
- * `name` attribute.  You can also use {@link NgModelGroup} if you'd like to create
+ * To register child controls with the form, you'll want to use `NgModel` with a
+ * `name` attribute.  You can also use `NgModelGroup` if you'd like to create
  * sub-groups within the form.
  *
  * You can listen to the directive's `ngSubmit` event to be notified when the user has
diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts
index f4164f2360e95..16c17f0ba1b42 100644
--- a/packages/forms/src/directives/ng_model.ts
+++ b/packages/forms/src/directives/ng_model.ts
@@ -48,10 +48,10 @@ const resolvedPromise = Promise.resolve(null);
 /**
  * @description
  *
- * Creates a {@link FormControl} instance from a domain model and binds it
+ * Creates a `FormControl` instance from a domain model and binds it
  * to a form control element.
  *
- * The {@link FormControl} instance will track the value, user interaction, and
+ * The `FormControl` instance will track the value, user interaction, and
  * validation status of the control and keep the view synced with the model. If used
  * within a parent form, the directive will also register itself with the form as a child
  * control.
@@ -59,18 +59,18 @@ const resolvedPromise = Promise.resolve(null);
  * This directive can be used by itself or as part of a larger form. All you need is the
  * `ngModel` selector to activate it.
  *
- * It accepts a domain model as an optional {@link Input}. If you have a one-way binding
+ * It accepts a domain model as an optional `Input`. If you have a one-way binding
  * to `ngModel` with `[]` syntax, changing the value of the domain model in the component
  * class will set the value in the view. If you have a two-way binding with `[()]` syntax
  * (also known as 'banana-box syntax'), the value in the UI will always be synced back to
  * the domain model in your class as well.
  *
- * If you wish to inspect the properties of the associated {@link FormControl} (like
+ * If you wish to inspect the properties of the associated `FormControl` (like
  * validity state), you can also export the directive into a local template variable using
  * `ngModel` as the key (ex: `#myVar="ngModel"`). You can then access the control using the
  * directive's `control` property, but most properties you'll need (like `valid` and `dirty`)
  * will fall through to the control anyway, so you can access them directly. You can see a
- * full list of properties directly available in {@link AbstractControlDirective}.
+ * full list of properties directly available in `AbstractControlDirective`.
  *
  * The following is an example of a simple standalone control using `ngModel`:
  *
@@ -94,8 +94,8 @@ const resolvedPromise = Promise.resolve(null);
  *
  * To see `ngModel` examples with different form control types, see:
  *
- * * Radio buttons: {@link RadioControlValueAccessor}
- * * Selects: {@link SelectControlValueAccessor}
+ * * Radio buttons: `RadioControlValueAccessor`
+ * * Selects: `SelectControlValueAccessor`
  *
  * **npm package**: `@angular/forms`
  *
diff --git a/packages/forms/src/directives/ng_model_group.ts b/packages/forms/src/directives/ng_model_group.ts
index 4da5587e39941..5f72c3545bf92 100644
--- a/packages/forms/src/directives/ng_model_group.ts
+++ b/packages/forms/src/directives/ng_model_group.ts
@@ -23,9 +23,9 @@ export const modelGroupProvider: any = {
 /**
  * @description
  *
- * Creates and binds a {@link FormGroup} instance to a DOM element.
+ * Creates and binds a `FormGroup` instance to a DOM element.
  *
- * This directive can only be used as a child of {@link NgForm} (or in other words,
+ * This directive can only be used as a child of `NgForm` (or in other words,
  * within `<form>` tags).
  *
  * Use this directive if you'd like to create a sub-group within a form. This can
diff --git a/packages/forms/src/directives/number_value_accessor.ts b/packages/forms/src/directives/number_value_accessor.ts
index 6eb72aeafb17d..96a823f72f936 100644
--- a/packages/forms/src/directives/number_value_accessor.ts
+++ b/packages/forms/src/directives/number_value_accessor.ts
@@ -18,7 +18,7 @@ export const NUMBER_VALUE_ACCESSOR: any = {
 
 /**
  * The accessor for writing a number value and listening to changes that is used by the
- * {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
+ * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
  *  ### Example
  *  ```
diff --git a/packages/forms/src/directives/radio_control_value_accessor.ts b/packages/forms/src/directives/radio_control_value_accessor.ts
index 7637100ea600c..93c61105eaa3c 100644
--- a/packages/forms/src/directives/radio_control_value_accessor.ts
+++ b/packages/forms/src/directives/radio_control_value_accessor.ts
@@ -59,10 +59,10 @@ export class RadioControlRegistry {
  *
  * Writes radio control values and listens to radio control changes.
  *
- * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
- * to keep the view synced with the {@link FormControl} model.
+ * Used by `NgModel`, `FormControlDirective`, and `FormControlName`
+ * to keep the view synced with the `FormControl` model.
  *
- * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
+ * If you have imported the `FormsModule` or the `ReactiveFormsModule`, this
  * value accessor will be active on any radio control that has a form directive. You do
  * **not** need to add a special selector to activate it.
  *
diff --git a/packages/forms/src/directives/range_value_accessor.ts b/packages/forms/src/directives/range_value_accessor.ts
index e695fde1163d3..0be4c6ed0d319 100644
--- a/packages/forms/src/directives/range_value_accessor.ts
+++ b/packages/forms/src/directives/range_value_accessor.ts
@@ -18,7 +18,7 @@ export const RANGE_VALUE_ACCESSOR: StaticProvider = {
 
 /**
  * The accessor for writing a range value and listening to changes that is used by the
- * {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
+ * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
  *  ### Example
  *  ```
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 1da0c3e9cee1c..5bc86796a3218 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_directive.ts
@@ -31,27 +31,27 @@ export const formControlBinding: any = {
 /**
  * @description
  *
- * Syncs a standalone {@link FormControl} instance to a form control element.
+ * Syncs a standalone `FormControl` instance to a form control element.
  *
- * This directive ensures that any values written to the {@link FormControl}
+ * This directive ensures that any values written to the `FormControl`
  * instance programmatically will be written to the DOM element (model -> view). Conversely,
  * any values written to the DOM element through user input will be reflected in the
- * {@link FormControl} instance (view -> model).
+ * `FormControl` instance (view -> model).
  *
- * Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
- * Simply create a {@link FormControl}, save it to your component class, and pass it into the
- * {@link FormControlDirective}.
+ * Use this directive if you'd like to create and manage a `FormControl` instance directly.
+ * Simply create a `FormControl`, save it to your component class, and pass it into the
+ * `FormControlDirective`.
  *
- * This directive is designed to be used as a standalone control.  Unlike {@link FormControlName},
- * it does not require that your {@link FormControl} instance be part of any parent
- * {@link FormGroup}, and it won't be registered to any {@link FormGroupDirective} that
+ * This directive is designed to be used as a standalone control.  Unlike `FormControlName`,
+ * it does not require that your `FormControl` instance be part of any parent
+ * `FormGroup`, and it won't be registered to any `FormGroupDirective` that
  * exists above it.
  *
  * **Get the value**: the `value` property is always synced and available on the
- * {@link FormControl} instance. See a full list of available properties in
- * {@link AbstractControl}.
+ * `FormControl` instance. See a full list of available properties in
+ * `AbstractControl`.
  *
- * **Set the value**: You can pass in an initial value when instantiating the {@link FormControl},
+ * **Set the value**: You can pass in an initial value when instantiating the `FormControl`,
  * or you can set it programmatically later using {@link AbstractControl#setValue setValue} or
  * {@link AbstractControl#patchValue patchValue}.
  *
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 05d0328eaede9..462c340d0e256 100644
--- a/packages/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts
@@ -30,30 +30,30 @@ export const controlNameBinding: any = {
 /**
  * @description
  *
- * Syncs a {@link FormControl} in an existing {@link FormGroup} to a form control
+ * Syncs a `FormControl` in an existing `FormGroup` to a form control
  * element by name.
  *
- * This directive ensures that any values written to the {@link FormControl}
+ * This directive ensures that any values written to the `FormControl`
  * instance programmatically will be written to the DOM element (model -> view). Conversely,
  * any values written to the DOM element through user input will be reflected in the
- * {@link FormControl} instance (view -> model).
+ * `FormControl` instance (view -> model).
  *
- * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
+ * This directive is designed to be used with a parent `FormGroupDirective` (selector:
  * `[formGroup]`).
  *
- * It accepts the string name of the {@link FormControl} instance you want to
- * link, and will look for a {@link FormControl} registered with that name in the
- * closest {@link FormGroup} or {@link FormArray} above it.
+ * It accepts the string name of the `FormControl` instance you want to
+ * link, and will look for a `FormControl` registered with that name in the
+ * closest `FormGroup` or `FormArray` above it.
  *
- * **Access the control**: You can access the {@link FormControl} associated with
+ * **Access the control**: You can access the `FormControl` associated with
  * this directive by using the {@link AbstractControl#get get} method.
  * Ex: `this.form.get('first');`
  *
- * **Get value**: the `value` property is always synced and available on the {@link FormControl}.
- * See a full list of available properties in {@link AbstractControl}.
+ * **Get value**: the `value` property is always synced and available on the `FormControl`.
+ * See a full list of available properties in `AbstractControl`.
  *
  *  **Set value**: You can set an initial value for the control when instantiating the
- *  {@link FormControl}, or you can set it programmatically later using
+ *  `FormControl`, or you can set it programmatically later using
  *  {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}.
  *
  * **Listen to value**: If you want to listen to changes in the value of the control, you can
@@ -69,12 +69,12 @@ export const controlNameBinding: any = {
  *
  * To see `formControlName` examples with different form control types, see:
  *
- * * Radio buttons: {@link RadioControlValueAccessor}
- * * Selects: {@link SelectControlValueAccessor}
+ * * Radio buttons: `RadioControlValueAccessor`
+ * * Selects: `SelectControlValueAccessor`
  *
  * **npm package**: `@angular/forms`
  *
- * **NgModule**: {@link ReactiveFormsModule}
+ * **NgModule**: `ReactiveFormsModule`
  *
  * ### Use with ngModel
  *
diff --git a/packages/forms/src/directives/reactive_directives/form_group_directive.ts b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
index eb5be54f25db0..6e8d724ad2514 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_directive.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_directive.ts
@@ -25,20 +25,20 @@ export const formDirectiveProvider: any = {
 /**
  * @description
  *
- * Binds an existing {@link FormGroup} to a DOM element.
+ * Binds an existing `FormGroup` to a DOM element.
  *
- * This directive accepts an existing {@link FormGroup} instance. It will then use this
- * {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup},
- * and {@link FormArray} instances to child {@link FormControlName}, {@link FormGroupName},
- * and {@link FormArrayName} directives.
+ * This directive accepts an existing `FormGroup` instance. It will then use this
+ * `FormGroup` instance to match any child `FormControl`, `FormGroup`,
+ * and `FormArray` instances to child `FormControlName`, `FormGroupName`,
+ * and `FormArrayName` directives.
  *
  * **Set value**: You can set the form's initial value when instantiating the
- * {@link FormGroup}, or you can set it programmatically later using the {@link FormGroup}'s
+ * `FormGroup`, or you can set it programmatically later using the `FormGroup`'s
  * {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}
  * methods.
  *
  * **Listen to value**: If you want to listen to changes in the value of the form, you can subscribe
- * to the {@link FormGroup}'s {@link AbstractControl#valueChanges valueChanges} event.  You can also
+ * to the `FormGroup`'s {@link AbstractControl#valueChanges valueChanges} event.  You can also
  * listen to its {@link AbstractControl#statusChanges statusChanges} event to be notified when the
  * validation status is re-calculated.
  *
@@ -54,7 +54,7 @@ export const formDirectiveProvider: any = {
  *
  * **npm package**: `@angular/forms`
  *
- * **NgModule**: {@link ReactiveFormsModule}
+ * **NgModule**: `ReactiveFormsModule`
  *
  *  @stable
  */
diff --git a/packages/forms/src/directives/reactive_directives/form_group_name.ts b/packages/forms/src/directives/reactive_directives/form_group_name.ts
index e3c1242a45389..ab0ae2f4004d4 100644
--- a/packages/forms/src/directives/reactive_directives/form_group_name.ts
+++ b/packages/forms/src/directives/reactive_directives/form_group_name.ts
@@ -26,30 +26,30 @@ export const formGroupNameProvider: any = {
 /**
  * @description
  *
- * Syncs a nested {@link FormGroup} to a DOM element.
+ * Syncs a nested `FormGroup` to a DOM element.
  *
- * This directive can only be used with a parent {@link FormGroupDirective} (selector:
+ * This directive can only be used with a parent `FormGroupDirective` (selector:
  * `[formGroup]`).
  *
- * It accepts the string name of the nested {@link FormGroup} you want to link, and
- * will look for a {@link FormGroup} registered with that name in the parent
- * {@link FormGroup} instance you passed into {@link FormGroupDirective}.
+ * It accepts the string name of the nested `FormGroup` you want to link, and
+ * will look for a `FormGroup` registered with that name in the parent
+ * `FormGroup` instance you passed into `FormGroupDirective`.
  *
  * Nested form groups can come in handy when you want to validate a sub-group of a
  * form separately from the rest or when you'd like to group the values of certain
  * controls into their own nested object.
  *
- * **Access the group**: You can access the associated {@link FormGroup} using the
+ * **Access the group**: You can access the associated `FormGroup` using the
  * {@link AbstractControl#get get} method. Ex: `this.form.get('name')`.
  *
  * You can also access individual controls within the group using dot syntax.
  * Ex: `this.form.get('name.first')`
  *
  * **Get the value**: the `value` property is always synced and available on the
- * {@link FormGroup}. See a full list of available properties in {@link AbstractControl}.
+ * `FormGroup`. See a full list of available properties in `AbstractControl`.
  *
  * **Set the value**: You can set an initial value for each child control when instantiating
- * the {@link FormGroup}, or you can set it programmatically later using
+ * the `FormGroup`, or you can set it programmatically later using
  * {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}.
  *
  * **Listen to value**: If you want to listen to changes in the value of the group, you can
@@ -97,37 +97,37 @@ export const formArrayNameProvider: any = {
 /**
  * @description
  *
- * Syncs a nested {@link FormArray} to a DOM element.
+ * Syncs a nested `FormArray` to a DOM element.
  *
- * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
+ * This directive is designed to be used with a parent `FormGroupDirective` (selector:
  * `[formGroup]`).
  *
- * It accepts the string name of the nested {@link FormArray} you want to link, and
- * will look for a {@link FormArray} registered with that name in the parent
- * {@link FormGroup} instance you passed into {@link FormGroupDirective}.
+ * It accepts the string name of the nested `FormArray` you want to link, and
+ * will look for a `FormArray` registered with that name in the parent
+ * `FormGroup` instance you passed into `FormGroupDirective`.
  *
  * Nested form arrays can come in handy when you have a group of form controls but
  * you're not sure how many there will be. Form arrays allow you to create new
  * form controls dynamically.
  *
- * **Access the array**: You can access the associated {@link FormArray} using the
- * {@link AbstractControl#get get} method on the parent {@link FormGroup}.
+ * **Access the array**: You can access the associated `FormArray` using the
+ * {@link AbstractControl#get get} method on the parent `FormGroup`.
  * Ex: `this.form.get('cities')`.
  *
  * **Get the value**: the `value` property is always synced and available on the
- * {@link FormArray}. See a full list of available properties in {@link AbstractControl}.
+ * `FormArray`. See a full list of available properties in `AbstractControl`.
  *
  * **Set the value**: You can set an initial value for each child control when instantiating
- * the {@link FormArray}, or you can set the value programmatically later using the
- * {@link FormArray}'s {@link AbstractControl#setValue setValue} or
+ * the `FormArray`, or you can set the value programmatically later using the
+ * `FormArray`'s {@link AbstractControl#setValue setValue} or
  * {@link AbstractControl#patchValue patchValue} methods.
  *
  * **Listen to value**: If you want to listen to changes in the value of the array, you can
- * subscribe to the {@link FormArray}'s {@link AbstractControl#valueChanges valueChanges} event.
+ * subscribe to the `FormArray`'s {@link AbstractControl#valueChanges valueChanges} event.
  * You can also listen to its {@link AbstractControl#statusChanges statusChanges} event to be
  * notified when the validation status is re-calculated.
  *
- * **Add new controls**: You can add new controls to the {@link FormArray} dynamically by calling
+ * **Add new controls**: You can add new controls to the `FormArray` dynamically by calling
  * its {@link FormArray#push push} method.
  * Ex: `this.form.get('cities').push(new FormControl());`
  *
diff --git a/packages/forms/src/directives/select_control_value_accessor.ts b/packages/forms/src/directives/select_control_value_accessor.ts
index 919efcbad2408..dcd9a5903ff8f 100644
--- a/packages/forms/src/directives/select_control_value_accessor.ts
+++ b/packages/forms/src/directives/select_control_value_accessor.ts
@@ -31,10 +31,10 @@ function _extractId(valueString: string): string {
  *
  * Writes values and listens to changes on a select element.
  *
- * Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
- * to keep the view synced with the {@link FormControl} model.
+ * Used by `NgModel`, `FormControlDirective`, and `FormControlName`
+ * to keep the view synced with the `FormControl` model.
  *
- * If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
+ * If you have imported the `FormsModule` or the `ReactiveFormsModule`, this
  * value accessor will be active on any select control that has a form directive. You do
  * **not** need to add a special selector to activate it.
  *
@@ -162,7 +162,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
  *
  * Marks `<option>` as dynamic, so Angular can be notified when options change.
  *
- * See docs for {@link SelectControlValueAccessor} for usage examples.
+ * See docs for `SelectControlValueAccessor` for usage examples.
  *
  * @stable
  */
diff --git a/packages/forms/src/directives/validators.ts b/packages/forms/src/directives/validators.ts
index 14070470cd184..da5952db08c79 100644
--- a/packages/forms/src/directives/validators.ts
+++ b/packages/forms/src/directives/validators.ts
@@ -62,7 +62,7 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = {
 
 /**
  * A Directive that adds the `required` validator to any controls marked with the
- * `required` attribute, via the {@link NG_VALIDATORS} binding.
+ * `required` attribute, via the `NG_VALIDATORS` binding.
  *
  * ### Example
  *
@@ -100,7 +100,7 @@ export class RequiredValidator implements Validator {
 
 /**
  * A Directive that adds the `required` validator to checkbox controls marked with the
- * `required` attribute, via the {@link NG_VALIDATORS} binding.
+ * `required` attribute, via the `NG_VALIDATORS` binding.
  *
  * ### Example
  *
@@ -123,7 +123,7 @@ export class CheckboxRequiredValidator extends RequiredValidator {
 }
 
 /**
- * Provider which adds {@link EmailValidator} to {@link NG_VALIDATORS}.
+ * Provider which adds `EmailValidator` to `NG_VALIDATORS`.
  */
 export const EMAIL_VALIDATOR: any = {
   provide: NG_VALIDATORS,
@@ -133,7 +133,7 @@ export const EMAIL_VALIDATOR: any = {
 
 /**
  * A Directive that adds the `email` validator to controls marked with the
- * `email` attribute, via the {@link NG_VALIDATORS} binding.
+ * `email` attribute, via the `NG_VALIDATORS` binding.
  *
  * ### Example
  *
@@ -179,7 +179,7 @@ export interface AsyncValidatorFn {
 }
 
 /**
- * Provider which adds {@link MinLengthValidator} to {@link NG_VALIDATORS}.
+ * Provider which adds `MinLengthValidator` to `NG_VALIDATORS`.
  *
  * ## Example:
  *
@@ -192,7 +192,7 @@ export const MIN_LENGTH_VALIDATOR: any = {
 };
 
 /**
- * A directive which installs the {@link MinLengthValidator} for any `formControlName`,
+ * A directive which installs the `MinLengthValidator` for any `formControlName`,
  * `formControl`, or control with `ngModel` that also has a `minlength` attribute.
  *
  * @stable
@@ -228,7 +228,7 @@ export class MinLengthValidator implements Validator,
 }
 
 /**
- * Provider which adds {@link MaxLengthValidator} to {@link NG_VALIDATORS}.
+ * Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`.
  *
  * ## Example:
  *
@@ -241,7 +241,7 @@ export const MAX_LENGTH_VALIDATOR: any = {
 };
 
 /**
- * A directive which installs the {@link MaxLengthValidator} for any `formControlName,
+ * A directive which installs the `MaxLengthValidator` for any `formControlName,
  * `formControl`,
  * or control with `ngModel` that also has a `maxlength` attribute.
  *
@@ -287,7 +287,7 @@ export const PATTERN_VALIDATOR: any = {
 
 /**
  * A Directive that adds the `pattern` validator to any controls marked with the
- * `pattern` attribute, via the {@link NG_VALIDATORS} binding. Uses attribute value
+ * `pattern` attribute, via the `NG_VALIDATORS` binding. Uses attribute value
  * as the regex to validate Control value against.  Follows pattern attribute
  * semantics; i.e. regex must match entire Control value.
  *
diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts
index 2587537a5394e..34c379d6b139b 100644
--- a/packages/forms/src/form_builder.ts
+++ b/packages/forms/src/form_builder.ts
@@ -14,7 +14,7 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
 /**
  * @description
  *
- * Creates an {@link AbstractControl} from a user-specified configuration.
+ * Creates an `AbstractControl` from a user-specified configuration.
  *
  * This is essentially syntactic sugar that shortens the `new FormGroup()`,
  * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
@@ -27,17 +27,17 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
  *
  *  * **npm package**: `@angular/forms`
  *
- *  * **NgModule**: {@link ReactiveFormsModule}
+ *  * **NgModule**: `ReactiveFormsModule`
  *
  * @stable
  */
 @Injectable()
 export class FormBuilder {
   /**
-   * Construct a new {@link FormGroup} with the given map of configuration.
+   * Construct a new `FormGroup` with the given map of configuration.
    * Valid keys for the `extra` parameter map are `validator` and `asyncValidator`.
    *
-   * See the {@link FormGroup} constructor for more details.
+   * See the `FormGroup` constructor for more details.
    */
   group(controlsConfig: {[key: string]: any}, extra: {[key: string]: any}|null = null): FormGroup {
     const controls = this._reduceControls(controlsConfig);
@@ -46,7 +46,7 @@ export class FormBuilder {
     return new FormGroup(controls, validator, asyncValidator);
   }
   /**
-   * Construct a new {@link FormControl} with the given `formState`,`validator`, and
+   * Construct a new `FormControl` with the given `formState`,`validator`, and
    * `asyncValidator`.
    *
    * `formState` can either be a standalone value for the form control or an object
@@ -60,7 +60,7 @@ export class FormBuilder {
   }
 
   /**
-   * Construct a {@link FormArray} from the given `controlsConfig` array of
+   * Construct a `FormArray` from the given `controlsConfig` array of
    * configuration, with the given optional `validator` and `asyncValidator`.
    */
   array(
diff --git a/packages/forms/src/forms.ts b/packages/forms/src/forms.ts
index 2f6f27c8a4ccf..d15871f88d831 100644
--- a/packages/forms/src/forms.ts
+++ b/packages/forms/src/forms.ts
@@ -9,8 +9,8 @@
 /**
  * @module
  * @description
- * This module is used for handling user input, by defining and building a {@link FormGroup} that
- * consists of {@link FormControl} objects, and mapping them onto the DOM. {@link FormControl}
+ * This module is used for handling user input, by defining and building a `FormGroup` that
+ * consists of `FormControl` objects, and mapping them onto the DOM. `FormControl`
  * objects can then be used to read information from the form DOM elements.
  *
  * Forms providers are not included in default providers; you must import these providers
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
index 1772a05dcc679..d75f516a57754 100644
--- a/packages/forms/src/model.ts
+++ b/packages/forms/src/model.ts
@@ -83,7 +83,7 @@ export type FormHooks = 'change' | 'blur' | 'submit';
 /**
  * @description
  *
- * Interface for options provided to an {@link AbstractControl}.
+ * Interface for options provided to an `AbstractControl`.
  *
  * @experimental
  */
@@ -113,7 +113,7 @@ function isOptionsObj(
 /**
  * @description
  *
- * This is the base class for {@link FormControl}, {@link FormGroup}, and {@link FormArray}.
+ * This is the base class for `FormControl`, `FormGroup`, and `FormArray`.
  *
  * It provides some of the shared behavior that all controls and groups of controls have, like
  * running validators, calculating status, and resetting state. It also defines the properties
@@ -676,9 +676,9 @@ export abstract class AbstractControl {
  * Tracks the value and validation status of an individual form control.
  *
  * This is one of the three fundamental building blocks of Angular forms, along with
- * {@link FormGroup} and {@link FormArray}.
+ * `FormGroup` and `FormArray`.
  *
- * When instantiating a {@link FormControl}, you can pass in an initial value as the
+ * When instantiating a `FormControl`, you can pass in an initial value as the
  * first argument. Example:
  *
  * ```ts
@@ -697,7 +697,7 @@ export abstract class AbstractControl {
  * console.log(ctrl.status);   // 'DISABLED'
  * ```
  *
- * The second {@link FormControl} argument can accept one of three things:
+ * The second `FormControl` argument can accept one of three things:
  * * a sync validator function
  * * an array of sync validator functions
  * * an options object containing validator and/or async validator functions
@@ -731,7 +731,7 @@ export abstract class AbstractControl {
  * You can also set `updateOn` to `'submit'`, which will delay value and validity
  * updates until the parent form of the control fires a submit event.
  *
- * See its superclass, {@link AbstractControl}, for more properties and methods.
+ * See its superclass, `AbstractControl`, for more properties and methods.
  *
  * * **npm package**: `@angular/forms`
  *
@@ -911,17 +911,17 @@ export class FormControl extends AbstractControl {
 /**
  * @description
  *
- * Tracks the value and validity state of a group of {@link FormControl} instances.
+ * Tracks the value and validity state of a group of `FormControl` instances.
  *
- * A `FormGroup` aggregates the values of each child {@link FormControl} into one object,
+ * A `FormGroup` aggregates the values of each child `FormControl` into one object,
  * with each control name as the key.  It calculates its status by reducing the statuses
  * of its children. For example, if one of the controls in a group is invalid, the entire
  * group becomes invalid.
  *
  * `FormGroup` is one of the three fundamental building blocks used to define forms in Angular,
- * along with {@link FormControl} and {@link FormArray}.
+ * along with `FormControl` and `FormArray`.
  *
- * When instantiating a {@link FormGroup}, pass in a collection of child controls as the first
+ * When instantiating a `FormGroup`, pass in a collection of child controls as the first
  * argument. The key for each child will be the name under which it is registered.
  *
  * ### Example
@@ -955,7 +955,7 @@ export class FormControl extends AbstractControl {
  * }
  * ```
  *
- * Like {@link FormControl} instances, you can alternatively choose to pass in
+ * Like `FormControl` instances, you can alternatively choose to pass in
  * validators and async validators as part of an options object.
  *
  * ```
@@ -1049,7 +1049,7 @@ export class FormGroup extends AbstractControl {
   }
 
   /**
-   *  Sets the value of the {@link FormGroup}. It accepts an object that matches
+   *  Sets the value of the `FormGroup`. It accepts an object that matches
    *  the structure of the group, with control names as keys.
    *
    *  ### Example
@@ -1080,7 +1080,7 @@ export class FormGroup extends AbstractControl {
   }
 
   /**
-   *  Patches the value of the {@link FormGroup}. It accepts an object with control
+   *  Patches the value of the `FormGroup`. It accepts an object with control
    *  names as keys, and will do its best to match the values to the correct controls
    *  in the group.
    *
@@ -1111,7 +1111,7 @@ export class FormGroup extends AbstractControl {
   }
 
   /**
-   * Resets the {@link FormGroup}. This means by default:
+   * Resets the `FormGroup`. This means by default:
    *
    * * The group and all descendants are marked `pristine`
    * * The group and all descendants are marked `untouched`
@@ -1152,7 +1152,7 @@ export class FormGroup extends AbstractControl {
   }
 
   /**
-   * The aggregate value of the {@link FormGroup}, including any disabled controls.
+   * The aggregate value of the `FormGroup`, including any disabled controls.
    *
    * If you'd like to include all values regardless of disabled status, use this method.
    * Otherwise, the `value` property is the best way to get the value of the group.
@@ -1254,17 +1254,17 @@ export class FormGroup extends AbstractControl {
 /**
  * @description
  *
- * Tracks the value and validity state of an array of {@link FormControl},
- * {@link FormGroup} or {@link FormArray} instances.
+ * Tracks the value and validity state of an array of `FormControl`,
+ * `FormGroup` or `FormArray` instances.
  *
- * A `FormArray` aggregates the values of each child {@link FormControl} into an array.
+ * A `FormArray` aggregates the values of each child `FormControl` into an array.
  * It calculates its status by reducing the statuses of its children. For example, if one of
  * the controls in a `FormArray` is invalid, the entire array becomes invalid.
  *
  * `FormArray` is one of the three fundamental building blocks used to define forms in Angular,
- * along with {@link FormControl} and {@link FormGroup}.
+ * along with `FormControl` and `FormGroup`.
  *
- * When instantiating a {@link FormArray}, pass in an array of child controls as the first
+ * When instantiating a `FormArray`, pass in an array of child controls as the first
  * argument.
  *
  * ### Example
@@ -1331,12 +1331,12 @@ export class FormArray extends AbstractControl {
   }
 
   /**
-   * Get the {@link AbstractControl} at the given `index` in the array.
+   * Get the `AbstractControl` at the given `index` in the array.
    */
   at(index: number): AbstractControl { return this.controls[index]; }
 
   /**
-   * Insert a new {@link AbstractControl} at the end of the array.
+   * Insert a new `AbstractControl` at the end of the array.
    */
   push(control: AbstractControl): void {
     this.controls.push(control);
@@ -1345,7 +1345,7 @@ export class FormArray extends AbstractControl {
     this._onCollectionChange();
   }
 
-  /** Insert a new {@link AbstractControl} at the given `index` in the array. */
+  /** Insert a new `AbstractControl` at the given `index` in the array. */
   insert(index: number, control: AbstractControl): void {
     this.controls.splice(index, 0, control);
 
@@ -1382,7 +1382,7 @@ export class FormArray extends AbstractControl {
   get length(): number { return this.controls.length; }
 
   /**
-   *  Sets the value of the {@link FormArray}. It accepts an array that matches
+   *  Sets the value of the `FormArray`. It accepts an array that matches
    *  the structure of the control.
    *
    * This method performs strict checks, so it will throw an error if you try
@@ -1412,7 +1412,7 @@ export class FormArray extends AbstractControl {
   }
 
   /**
-   *  Patches the value of the {@link FormArray}. It accepts an array that matches the
+   *  Patches the value of the `FormArray`. It accepts an array that matches the
    *  structure of the control, and will do its best to match the values to the correct
    *  controls in the group.
    *
@@ -1441,7 +1441,7 @@ export class FormArray extends AbstractControl {
   }
 
   /**
-   * Resets the {@link FormArray}. This means by default:
+   * Resets the `FormArray`. This means by default:
    *
    * * The array and all descendants are marked `pristine`
    * * The array and all descendants are marked `untouched`
diff --git a/packages/forms/src/validators.ts b/packages/forms/src/validators.ts
index 7595e3dc6a582..9198a76f10c93 100644
--- a/packages/forms/src/validators.ts
+++ b/packages/forms/src/validators.ts
@@ -18,7 +18,7 @@ function isEmptyInputValue(value: any): boolean {
 }
 
 /**
- * Providers for validators to be used for {@link FormControl}s in a form.
+ * Providers for validators to be used for `FormControl`s in a form.
  *
  * Provide this using `multi: true` to add validators.
  *
@@ -41,12 +41,12 @@ function isEmptyInputValue(value: any): boolean {
 export const NG_VALIDATORS = new InjectionToken<Array<Validator|Function>>('NgValidators');
 
 /**
- * Providers for asynchronous validators to be used for {@link FormControl}s
+ * Providers for asynchronous validators to be used for `FormControl`s
  * in a form.
  *
  * Provide this using `multi: true` to add validators.
  *
- * See {@link NG_VALIDATORS} for more details.
+ * See `NG_VALIDATORS` for more details.
  *
  * @stable
  */
@@ -59,7 +59,7 @@ const EMAIL_REGEXP =
 /**
  * Provides a set of validators used by form controls.
  *
- * A validator is a function that processes a {@link FormControl} or collection of
+ * A validator is a function that processes a `FormControl` or collection of
  * controls and returns a map of errors. A null map means that validation has passed.
  *
  * ### Example