docs(forms): migrate `@whatItDoes` tags to the description (#23186)

We get the overview for the doc by splitting off the first
paragraph.

PR Close #23186

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.
  *

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.
  *

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).
  *

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.
  *

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.

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
  *
- * In other words, this directive ensures that any values written to the {@link FormControl}
+ * Syncs a standalone {@link FormControl} instance to a form control element.
+ *
+ * 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}.

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]`).
  *

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},

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]`).
  *

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

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
  *
- * It is essentially syntactic sugar that shortens the `new FormGroup()`,
+ * Creates an {@link 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
  * forms.
  *
- * @description
- *
  * To use, inject `FormBuilder` into your component class. You can then call its methods
  * directly.
  *

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
+ * @description
- * {@link FormArray}.
+ *
+ * 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,13 +671,13 @@ export abstract class AbstractControl {
 }
 
 /**
- * @whatItDoes Tracks the value and validation status of an individual form control.
- *
- * It is one of the three fundamental building blocks of Angular forms, along with
- * {@link FormGroup} and {@link FormArray}.
- *
  * @description
  *
+ * 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}.
+ *
  * 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}
+ * @description
- * instances.
+ *
+ * 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.
  *