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
+ * @usageNotes
- *  ```
+ * ### Example
- *  <input type="checkbox" name="rememberLogin" ngModel>
+ *
- *  ```
+ * ```
+ * <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
+ * @usageNotes
- *  ```
+ * ### Example
- *  <input type="text" name="searchQuery" ngModel>
+ *
- *  ```
+ * ```
+ * <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
+ * @usageNotes
- *  ```
+ * ### Example
- *  <input type="number" [(ngModel)]="age">
+ *
- *  ```
+ * ```
+ * <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
+ * @usageNotes
- *  ```
+ * ### Example
- *  <input type="range" [(ngModel)]="age" >
+ *
- *  ```
+ * ```
+ * <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 {
+  validate(control: AbstractControl): ValidationErrors|null {
-    return this.required ? Validators.required(c) : 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 {
+  validate(control: AbstractControl): ValidationErrors|null {
-    return this.required ? Validators.requiredTrue(c) : 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 {
+  validate(control: AbstractControl): ValidationErrors|null {
-    return this._enabled ? Validators.email(c) : 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 {
+  validate(control: AbstractControl): ValidationErrors|null {
-    return this.minlength == null ? null : this._validator(c);
+    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 {
+  validate(control: AbstractControl): ValidationErrors|null {
-    return this.maxlength != null ? this._validator(c) : 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; }
 

packages/forms/src/model.ts

@@ -599,6 +599,7 @@ export abstract class AbstractControl {
    *
    * Calling `setErrors` also updates the validity of the parent control.
    *
+   * @usageNotes
    * ### Manually set the errors for a control
    *
    * ```
@@ -626,6 +627,7 @@ export abstract class AbstractControl {
    * @param path A dot-delimited string or array of string/number values that define the path to the
    * control.
    *
+   * @usageNotes
    * ### Retrieve a nested control
    *
    * For example, to get a `name` control nested within a `person` sub-group:
@@ -1225,6 +1227,7 @@ export class FormGroup extends AbstractControl {
    * Sets the value of the `FormGroup`. It accepts an object that matches
    * the structure of the group, with control names as keys.
    *
+   * @usageNotes
    * ### Set the complete value for the form group
    *
    * ```
@@ -1237,8 +1240,8 @@ export class FormGroup extends AbstractControl {
    *
    * form.setValue({first: 'Nancy', last: 'Drew'});
    * console.log(form.value);   // {first: 'Nancy', last: 'Drew'}
-   *
    * ```
+   *
    * @throws When strict checks fail, such as setting the value of a control
    * that doesn't exist or if you excluding the value of a control.
    *
@@ -1272,19 +1275,19 @@ export class FormGroup extends AbstractControl {
    *
    * It accepts both super-sets and sub-sets of the group without throwing an error.
    *
+   * @usageNotes
    * ### Patch the value for a form group
    *
-   *  ```
+   * ```
-   *  const form = new FormGroup({
+   * const form = new FormGroup({
-   *     first: new FormControl(),
+   *    first: new FormControl(),
-   *     last: new FormControl()
+   *    last: new FormControl()
-   *  });
+   * });
-   *  console.log(form.value);   // {first: null, last: null}
+   * console.log(form.value);   // {first: null, last: null}
    *
-   *  form.patchValue({first: 'Nancy'});
+   * form.patchValue({first: 'Nancy'});
-   *  console.log(form.value);   // {first: 'Nancy', last: null}
+   * console.log(form.value);   // {first: 'Nancy', last: null}
-   *
+   * ```
-   *  ```
    *
    * @param value The object that matches the structure of the group.
    * @param options Configuration options that determine how the control propagates changes and
@@ -1641,6 +1644,7 @@ export class FormArray extends AbstractControl {
    * to set the value of a control that doesn't exist or if you exclude the
    * value of a control.
    *
+   * @usageNotes
    * ### Set the values for the controls in the form array
    *
    * ```
@@ -1683,6 +1687,7 @@ export class FormArray extends AbstractControl {
    *
    * It accepts both super-sets and sub-sets of the array without throwing an error.
    *
+   * @usageNotes
    * ### Patch the values for controls in a form array
    *
    * ```
@@ -1726,6 +1731,7 @@ export class FormArray extends AbstractControl {
    * that matches the structure of the control. The state is a standalone value
    * or a form state object with both a value and a disabled status.
    *
+   * @usageNotes
    * ### Reset the values in a form array
    *
    * ```ts

packages/forms/src/validators.ts

@@ -22,12 +22,12 @@ function isEmptyInputValue(value: any): boolean {
  * An `InjectionToken` for registering additional synchronous validators used with `AbstractControl`s.
  *
  * @see `NG_ASYNC_VALIDATORS`
- * 
+ *
  * @usageNotes
- * 
+ *
  * ### Providing a custom validator
- * 
+ *
- * The following example registers a custom validator directive. Adding the validator to the 
+ * The following example registers a custom validator directive. Adding the validator to the
  * existing collection of validators requires the `multi: true` option.
  *
  * ```typescript
@@ -50,7 +50,7 @@ export const NG_VALIDATORS = new InjectionToken<Array<Validator|Function>>('NgVa
  * An `InjectionToken` for registering additional asynchronous validators used with `AbstractControl`s.
  *
  * @see `NG_VALIDATORS`
- * 
+ *
  */
 export const NG_ASYNC_VALIDATORS =
     new InjectionToken<Array<Validator|Function>>('NgAsyncValidators');
@@ -64,7 +64,7 @@ const EMAIL_REGEXP =
  *
  * A validator is a function that processes a `FormControl` or collection of
  * controls and returns an error map or null. A null map means that validation has passed.
- * 
+ *
  * @see [Form Validation](/guide/form-validation)
  *
  */
@@ -322,7 +322,7 @@ export class Validators {
    * @description
    * Validator that performs no operation.
    */
-  static nullValidator(c: AbstractControl): ValidationErrors|null { return null; }
+  static nullValidator(control: AbstractControl): ValidationErrors|null { return null; }
 
   /**
    * @description

tools/public_api_guard/forms/forms.d.ts

@@ -104,11 +104,11 @@ export declare class AbstractFormGroupDirective extends ControlContainer impleme
 
 /** @experimental */
 export interface AsyncValidator extends Validator {
-    validate(c: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
+    validate(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
 }
 
 export interface AsyncValidatorFn {
-    (c: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
+    (control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
 }
 
 export declare class CheckboxControlValueAccessor implements ControlValueAccessor {
@@ -123,7 +123,7 @@ export declare class CheckboxControlValueAccessor implements ControlValueAccesso
 
 /** @experimental */
 export declare class CheckboxRequiredValidator extends RequiredValidator {
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 /** @experimental */
@@ -156,7 +156,7 @@ export declare class DefaultValueAccessor implements ControlValueAccessor {
 export declare class EmailValidator implements Validator {
     email: boolean | string;
     registerOnValidatorChange(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export interface Form {
@@ -336,14 +336,14 @@ export declare class MaxLengthValidator implements Validator, OnChanges {
     maxlength: string;
     ngOnChanges(changes: SimpleChanges): void;
     registerOnValidatorChange(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export declare class MinLengthValidator implements Validator, OnChanges {
     minlength: string;
     ngOnChanges(changes: SimpleChanges): void;
     registerOnValidatorChange(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export declare const NG_ASYNC_VALIDATORS: InjectionToken<(Function | Validator)[]>;
@@ -437,7 +437,7 @@ export declare class PatternValidator implements Validator, OnChanges {
     pattern: string | RegExp;
     ngOnChanges(changes: SimpleChanges): void;
     registerOnValidatorChange(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export declare class RadioControlValueAccessor implements ControlValueAccessor, OnDestroy, OnInit {
@@ -464,7 +464,7 @@ export declare class ReactiveFormsModule {
 export declare class RequiredValidator implements Validator {
     required: boolean | string;
     registerOnValidatorChange(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export declare class SelectControlValueAccessor implements ControlValueAccessor {
@@ -498,11 +498,11 @@ export declare type ValidationErrors = {
 
 export interface Validator {
     registerOnValidatorChange?(fn: () => void): void;
-    validate(c: AbstractControl): ValidationErrors | null;
+    validate(control: AbstractControl): ValidationErrors | null;
 }
 
 export interface ValidatorFn {
-    (c: AbstractControl): ValidationErrors | null;
+    (control: AbstractControl): ValidationErrors | null;
 }
 
 export declare class Validators {
@@ -514,7 +514,7 @@ export declare class Validators {
     static maxLength(maxLength: number): ValidatorFn;
     static min(min: number): ValidatorFn;
     static minLength(minLength: number): ValidatorFn;
-    static nullValidator(c: AbstractControl): ValidationErrors | null;
+    static nullValidator(control: AbstractControl): ValidationErrors | null;
     static pattern(pattern: string | RegExp): ValidatorFn;
     static required(control: AbstractControl): ValidationErrors | null;
     static requiredTrue(control: AbstractControl): ValidationErrors | null;