docs(forms): move extended text to @usageNotes (#26039)

Headings are not allowed in the basic description block.

PR Close #26039

packages/forms/src/directives/checkbox_value_accessor.ts

@@ -19,10 +19,12 @@ export const CHECKBOX_VALUE_ACCESSOR: any = {
 /**
  * The accessor for writing a value and listening to changes on a checkbox input element.
  *
- *  ### Example
- *  ```
- *  <input type="checkbox" name="rememberLogin" ngModel>
- *  ```
+ * @usageNotes
+ * ### Example
+ *
+ * ```
+ * <input type="checkbox" name="rememberLogin" ngModel>
+ * ```
  *
  * @ngModule FormsModule
  * @ngModule ReactiveFormsModule

packages/forms/src/directives/control_value_accessor.ts

@@ -15,7 +15,7 @@ import {InjectionToken} from '@angular/core';
  *
  * Implement this interface to create a custom form control directive
  * that integrates with Angular forms.
- * 
+ *
  * @see DefaultValueAccessor
  */
 export interface ControlValueAccessor {
@@ -26,6 +26,7 @@ export interface ControlValueAccessor {
    * This method is called by the forms API to write to the view when programmatic
    * changes from model to view are requested.
    *
+   * @usageNotes
    * ### Write a value to the element
    *
    * The following example writes a value to the native DOM element.
@@ -51,6 +52,7 @@ export interface ControlValueAccessor {
    * When implementing the `registerOnChange` method in your own value accessor,
    * save the given function so your class calls it at the appropriate time.
    *
+   * @usageNotes
    * ### Store the change function
    *
    * The following example stores the provided function as an internal method.
@@ -83,6 +85,7 @@ export interface ControlValueAccessor {
    * function so your class calls it when the control should be considered
    * blurred or "touched".
    *
+   * @usageNotes
    * ### Store the callback function
    *
    * The following example stores the provided function as an internal method.
@@ -112,6 +115,7 @@ export interface ControlValueAccessor {
    * or from 'DISABLED'. Depending on the status, it enables or disables the
    * appropriate DOM element.
    *
+   * @usageNotes
    * The following is an example of writing the disabled property to a native DOM element:
    *
    * ```ts

packages/forms/src/directives/default_value_accessor.ts

@@ -35,10 +35,12 @@ 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
  * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
- *  ### Example
- *  ```
- *  <input type="text" name="searchQuery" ngModel>
- *  ```
+ * @usageNotes
+ * ### Example
+ *
+ * ```
+ * <input type="text" name="searchQuery" ngModel>
+ * ```
  *
  * @ngModule FormsModule
  * @ngModule ReactiveFormsModule

packages/forms/src/directives/number_value_accessor.ts

@@ -20,10 +20,13 @@ export const NUMBER_VALUE_ACCESSOR: any = {
  * The accessor for writing a number value and listening to changes that is used by the
  * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
- *  ### Example
- *  ```
- *  <input type="number" [(ngModel)]="age">
- *  ```
+ * @usageNotes
+ * ### Example
+ *
+ * ```
+ * <input type="number" [(ngModel)]="age">
+ * ```
+ *
  * @ngModule FormsModule
  * @ngModule ReactiveFormsModule
  */

packages/forms/src/directives/radio_control_value_accessor.ts

@@ -66,6 +66,7 @@ export class RadioControlRegistry {
  * 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.
  *
+ * @usageNotes
  * ### How to use radio buttons with form directives
  *
  * To use radio buttons in a template-driven form, you'll want to ensure that radio buttons

packages/forms/src/directives/range_value_accessor.ts

@@ -20,10 +20,13 @@ export const RANGE_VALUE_ACCESSOR: StaticProvider = {
  * The accessor for writing a range value and listening to changes that is used by the
  * `NgModel`, `FormControlDirective`, and `FormControlName` directives.
  *
- *  ### Example
- *  ```
- *  <input type="range" [(ngModel)]="age" >
- *  ```
+ * @usageNotes
+ * ### Example
+ *
+ * ```
+ * <input type="range" [(ngModel)]="age" >
+ * ```
+ *
  * @ngModule FormsModule
  * @ngModule ReactiveFormsModule
  */

packages/forms/src/directives/reactive_directives/form_control_directive.ts

@@ -38,6 +38,7 @@ export const formControlBinding: any = {
  * any values written to the DOM element through user input will be reflected in the
  * `FormControl` instance (view -> model).
  *
+ * @usageNotes
  * 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`.
@@ -70,6 +71,7 @@ export const formControlBinding: any = {
  * form directives has been deprecated in Angular v6 and will be removed in Angular v7.
  *
  * Now deprecated:
+ *
  * ```html
  * <input [formControl]="control" [(ngModel)]="value">
  * ```

packages/forms/src/directives/reactive_directives/form_control_name.ts

@@ -38,6 +38,7 @@ export const controlNameBinding: any = {
  * any values written to the DOM element through user input will be reflected in the
  * `FormControl` instance (view -> model).
  *
+ * @usageNotes
  * This directive is designed to be used with a parent `FormGroupDirective` (selector:
  * `[formGroup]`).
  *
@@ -78,6 +79,7 @@ export const controlNameBinding: any = {
  * form directives has been deprecated in Angular v6 and will be removed in Angular v7.
  *
  * Now deprecated:
+ *
  * ```html
  * <form [formGroup]="form">
  *   <input formControlName="first" [(ngModel)]="value">

packages/forms/src/directives/reactive_directives/form_group_directive.ts

@@ -32,6 +32,7 @@ export const formDirectiveProvider: any = {
  * and `FormArray` instances to child `FormControlName`, `FormGroupName`,
  * and `FormArrayName` directives.
  *
+ * @usageNotes
  * **Set value**: You can set the form's initial value when instantiating the
  * `FormGroup`, or you can set it programmatically later using the `FormGroup`'s
  * {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}

packages/forms/src/directives/reactive_directives/form_group_name.ts

@@ -39,6 +39,7 @@ export const formGroupNameProvider: any = {
  * form separately from the rest or when you'd like to group the values of certain
  * controls into their own nested object.
  *
+ * @usageNotes
  * **Access the group**: You can access the associated `FormGroup` using the
  * {@link AbstractControl#get get} method. Ex: `this.form.get('name')`.
  *
@@ -107,6 +108,7 @@ export const formArrayNameProvider: any = {
  * you're not sure how many there will be. Form arrays allow you to create new
  * form controls dynamically.
  *
+ * @usageNotes
  * **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')`.

packages/forms/src/directives/select_control_value_accessor.ts

@@ -38,6 +38,7 @@ function _extractId(valueString: string): string {
  * 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.
  *
+ * @usageNotes
  * ### How to use select controls with form directives
  *
  * To use a select in a template-driven form, simply add an `ngModel` and a `name`
@@ -66,7 +67,7 @@ function _extractId(valueString: string): string {
  * `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
  * If `compareWith` is given, Angular selects option by the return value of the function.
  *
- * #### Syntax
+ * ### Syntax
  *
  * ```
  * <select [compareWith]="compareFn"  [(ngModel)]="selectedCountries">

packages/forms/src/directives/select_multiple_control_value_accessor.ts

@@ -43,7 +43,8 @@ abstract class HTMLCollection {
 /**
  * The accessor for writing a value and listening to changes on a select element.
  *
- *  ### Caveat: Options selection
+ * @usageNotes
+ * ### Caveat: Options selection
  *
  * Angular uses object identity to select options. It's possible for the identities of items
  * to change while the data does not. This can happen, for example, if the items are produced
@@ -54,7 +55,7 @@ abstract class HTMLCollection {
  * input. `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
  * If `compareWith` is given, Angular selects options by the return value of the function.
  *
- * #### Syntax
+ * ### Syntax
  *
  * ```
  * <select multiple [compareWith]="compareFn"  [(ngModel)]="selectedCountries">
@@ -169,6 +170,7 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
 /**
  * Marks `<option>` as dynamic, so Angular can be notified when options change.
  *
+ * @usageNotes
  * ### Example
  *
  * ```

packages/forms/src/directives/validators.ts

@@ -40,7 +40,7 @@ export type ValidationErrors = {
  *   providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}]
  * })
  * class CustomValidatorDirective implements Validator {
- *   validate(c: AbstractControl): ValidationErrors|null {
+ *   validate(control: AbstractControl): ValidationErrors|null {
  *     return {'custom': true};
  *   }
  * }
@@ -56,7 +56,7 @@ export interface Validator {
    * @returns A map of validation errors if validation fails,
    * otherwise null.
    */
-  validate(c: AbstractControl): ValidationErrors|null;
+  validate(control: AbstractControl): ValidationErrors|null;
 
   /**
    * @description
@@ -87,7 +87,7 @@ export interface Validator {
  * true}]
  * })
  * class CustomAsyncValidatorDirective implements AsyncValidator {
- *   validate(c: AbstractControl): Observable<ValidationErrors|null> {
+ *   validate(control: AbstractControl): Observable<ValidationErrors|null> {
  *     return observableOf({'custom': true});
  *   }
  * }
@@ -105,7 +105,8 @@ export interface AsyncValidator extends Validator {
    * @returns A promise or observable that resolves a map of validation errors
    * if validation fails, otherwise null.
    */
-  validate(c: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
+  validate(control: AbstractControl):
+      Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
 }
 
 export const REQUIRED_VALIDATOR: StaticProvider = {
@@ -125,6 +126,7 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = {
  * A Directive that adds the `required` validator to any controls marked with the
  * `required` attribute, via the `NG_VALIDATORS` binding.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -154,8 +156,8 @@ export class RequiredValidator implements Validator {
     if (this._onChange) this._onChange();
   }
 
-  validate(c: AbstractControl): ValidationErrors|null {
-    return this.required ? Validators.required(c) : null;
+  validate(control: AbstractControl): ValidationErrors|null {
+    return this.required ? Validators.required(control) : null;
   }
 
   registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@@ -166,6 +168,7 @@ export class RequiredValidator implements Validator {
  * A Directive that adds the `required` validator to checkbox controls marked with the
  * `required` attribute, via the `NG_VALIDATORS` binding.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -183,8 +186,8 @@ export class RequiredValidator implements Validator {
   host: {'[attr.required]': 'required ? "" : null'}
 })
 export class CheckboxRequiredValidator extends RequiredValidator {
-  validate(c: AbstractControl): ValidationErrors|null {
-    return this.required ? Validators.requiredTrue(c) : null;
+  validate(control: AbstractControl): ValidationErrors|null {
+    return this.required ? Validators.requiredTrue(control) : null;
   }
 }
 
@@ -201,6 +204,7 @@ export const EMAIL_VALIDATOR: any = {
  * A Directive that adds the `email` validator to controls marked with the
  * `email` attribute, via the `NG_VALIDATORS` binding.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -229,23 +233,24 @@ export class EmailValidator implements Validator {
     if (this._onChange) this._onChange();
   }
 
-  validate(c: AbstractControl): ValidationErrors|null {
-    return this._enabled ? Validators.email(c) : null;
+  validate(control: AbstractControl): ValidationErrors|null {
+    return this._enabled ? Validators.email(control) : null;
   }
 
   registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
 }
 
-export interface ValidatorFn { (c: AbstractControl): ValidationErrors|null; }
+export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; }
 
 export interface AsyncValidatorFn {
-  (c: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
+  (control: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
 }
 
 /**
  * Provider which adds `MinLengthValidator` to `NG_VALIDATORS`.
  *
- * ## Example:
+ * @usageNotes
+ * ### Example:
  *
  * {@example common/forms/ts/validators/validators.ts region='min'}
  */
@@ -284,8 +289,8 @@ export class MinLengthValidator implements Validator,
     }
   }
 
-  validate(c: AbstractControl): ValidationErrors|null {
-    return this.minlength == null ? null : this._validator(c);
+  validate(control: AbstractControl): ValidationErrors|null {
+    return this.minlength == null ? null : this._validator(control);
   }
 
   registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@@ -298,7 +303,8 @@ export class MinLengthValidator implements Validator,
 /**
  * Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`.
  *
- * ## Example:
+ * @usageNotes
+ * ### Example:
  *
  * {@example common/forms/ts/validators/validators.ts region='max'}
  */
@@ -337,8 +343,8 @@ export class MaxLengthValidator implements Validator,
     }
   }
 
-  validate(c: AbstractControl): ValidationErrors|null {
-    return this.maxlength != null ? this._validator(c) : null;
+  validate(control: AbstractControl): ValidationErrors|null {
+    return this.maxlength != null ? this._validator(control) : null;
   }
 
   registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@@ -362,6 +368,7 @@ export const PATTERN_VALIDATOR: any = {
  * as the regex to validate Control value against.  Follows pattern attribute
  * semantics; i.e. regex must match entire Control value.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -393,7 +400,7 @@ export class PatternValidator implements Validator,
     }
   }
 
-  validate(c: AbstractControl): ValidationErrors|null { return this._validator(c); }
+  validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); }
 
   registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }