docs(docs-infra): Update with review changes (#24255)

PR Close #24255

packages/forms/src/model.ts

@@ -161,14 +161,14 @@ export abstract class AbstractControl {
   /**
    * @description
    * The validation status of the control. There are four possible
-   * validation statuses:
+   * validation status values:
    *
-   * * **VALID**:  control has passed all validation checks
+   * * **VALID**: This control has passed all validation checks.
-   * * **INVALID**: control has failed at least one validation check
+   * * **INVALID**: This control has failed at least one validation check.
-   * * **PENDING**: control is in the midst of conducting a validation check
+   * * **PENDING**: This control is in the midst of conducting a validation check.
-   * * **DISABLED**: control is exempt from validation checks
+   * * **DISABLED**: This control is exempt from validation checks.
    *
-   * These statuses are mutually exclusive, so a control cannot be
+   * These status values are mutually exclusive, so a control cannot be
    * both valid AND invalid or invalid AND disabled.
    */
   public readonly status: string;
@@ -177,8 +177,8 @@ export abstract class AbstractControl {
    * @description
    * A control is `valid` when its `status` is `VALID`.
    *
-   * In order to have this status, the control must have passed all its
+   * True if the control has passed all of its validation tests, 
-   * validation checks.
+   * false otherwise.
    */
   get valid(): boolean { return this.status === VALID; }
 
@@ -186,8 +186,8 @@ export abstract class AbstractControl {
    * @description
    * A control is `invalid` when its `status` is `INVALID`.
    *
-   * In order to have this status, the control must have failed
+   * True if this control has failed one or more of its validation checks,
-   * at least one of its validation checks.
+   * false otherwise.
    */
   get invalid(): boolean { return this.status === INVALID; }
 
@@ -195,15 +195,17 @@ export abstract class AbstractControl {
    * @description
    * A control is `pending` when its `status` is `PENDING`.
    *
-   * In order to have this status, the control must be in the
+   * True if this control is in the process of conducting a validation check, 
-   * middle of conducting a validation check.
+   * false otherwise.
    */
   get pending(): boolean { return this.status == PENDING; }
 
   /**
    * @description
    * A control is `disabled` when its `status` is `DISABLED`.
-   *
+   * 
+   * True if the control is disabled, false otherwise.
+   * 
    * Disabled controls are exempt from validation checks and
    * are not included in the aggregate value of their ancestor
    * controls.
@@ -213,16 +215,17 @@ export abstract class AbstractControl {
   /**
    * @description
    * A control is `enabled` as long as its `status` is not `DISABLED`.
-   *
+   * 
-   * In other words, it has a status of `VALID`, `INVALID`, or
+   * True if the control has any status other than 'DISABLED', 
-   * `PENDING`.
+   * false if the status is 'DISABLED'.
+   * 
    */
   get enabled(): boolean { return this.status !== DISABLED; }
 
   /**
    * @description
-   * Returns any errors generated by failing validation. If there
+   * An object containing any errors generated by failing validation,
-   * are no errors, it will return null.
+   * or null if there are no errors.
    */
   public readonly errors: ValidationErrors|null;
 
@@ -231,8 +234,8 @@ export abstract class AbstractControl {
    * A control is `pristine` if the user has not yet changed
    * the value in the UI.
    *
-   * Programmatic changes to a control's value will
+   * True if the user has not yet changed the value in the UI; compare `dirty`.
-   * **not** mark it dirty.
+   * Programmatic changes to a control's value do not mark it dirty.
    */
   public readonly pristine: boolean = true;
 
@@ -241,8 +244,8 @@ export abstract class AbstractControl {
    * A control is `dirty` if the user has changed the value
    * in the UI.
    *
-   * Programmatic changes to a control's value will
+   * True if the user has changed the value of this control in the UI; compare `pristine`.
-   * **not** mark it dirty.
+   * Programmatic changes to a control's value do not mark it dirty.
    */
   get dirty(): boolean { return !this.pristine; }
 
@@ -262,21 +265,21 @@ export abstract class AbstractControl {
 
   /**
    * @description
-   * Emits an event every time the value of the control changes, in
+   * An observable that emits an event every time the value of the control changes, in
    * the UI or programmatically.
    */
   public readonly valueChanges: Observable<any>;
 
   /**
    * @description
-   * Emits an event every time the validation status of the control
+   * An observable that emits an event every time the validation `status` of the control
    * is re-calculated.
    */
   public readonly statusChanges: Observable<any>;
 
   /**
    * @description
-   * Returns the update strategy of the `AbstractControl` (i.e.
+   * Reports the update strategy of the `AbstractControl` (i.e.
    * the event on which the control will update itself).
    * Possible values: `'change'` | `'blur'` | `'submit'`
    * Default value: `'change'`
@@ -319,9 +322,9 @@ export abstract class AbstractControl {
    * @description
    * Marks the control as `touched`.
    *
-   *  @param opts Configure options that happen when marked as touched
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `touched`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model. Defaults to false
+   * marks all direct ancestors, in order to maintain the model.
    */
   markAsTouched(opts: {onlySelf?: boolean} = {}): void {
     (this as{touched: boolean}).touched = true;
@@ -339,9 +342,9 @@ export abstract class AbstractControl {
    * to maintain the model, and re-calculate the `touched` status of all parent
    * controls.
    *
-   *  @param opts Configure options that happen when marked as untouched
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `touched`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model. Defaults to false
+   * marks all direct ancestors, in order to maintain the model.
    */
   markAsUntouched(opts: {onlySelf?: boolean} = {}): void {
     (this as{touched: boolean}).touched = false;
@@ -359,9 +362,9 @@ export abstract class AbstractControl {
    * @description
    * Marks the control as `dirty`.
    *
-   *  @param opts Configure options that happen when marked as dirty
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `dirty` to maintain
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model. Defaults to false
+   * marks all direct ancestors, in order to maintain the model.
    */
   markAsDirty(opts: {onlySelf?: boolean} = {}): void {
     (this as{pristine: boolean}).pristine = false;
@@ -379,9 +382,9 @@ export abstract class AbstractControl {
    * to maintain the model, and re-calculate the `pristine` status of all parent
    * controls.
    *
-   *  @param opts Configure options that happen when marked as pristine
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `pristine`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model. Defaults to false
+   * marks all direct ancestors, in order to maintain the model.
    */
   markAsPristine(opts: {onlySelf?: boolean} = {}): void {
     (this as{pristine: boolean}).pristine = true;
@@ -400,10 +403,11 @@ export abstract class AbstractControl {
    *
    * An event will be emitted by `statusChanges` by default.
    *
-   *  @param opts Configure options that happen when marked as untouched
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `untouched`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model.
+   * marks all direct ancestors, in order to maintain the model.
-   * * If `emitEvent` is false, `statusChanges` will not emit an event.
+   * * `emitEvent`: When false, `statusChanges` will not emit an event.
+   * 
    */
   markAsPending(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
     (this as{status: string}).status = PENDING;
@@ -424,10 +428,11 @@ export abstract class AbstractControl {
    *
    * If the control has children, all children will be disabled to maintain the model.
    *
-   *  @param opts Configure options that happen when disabled
+   *  @param opts Configuration options that how marking is applied.
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `disabled`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model.
+   * marks all direct ancestors, in order to maintain the model.
-   * * If `emitEvent` is false, `statusChanges` and `valueChanges` will not emit an event.
+   * * `emitEvent`: When false, `statusChanges` and `valueChanges` will not emit an event. Otherwise,
+   * both Observables will emit a status and value event.
    */
   disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
     (this as{status: string}).status = DISABLED;
@@ -451,12 +456,13 @@ export abstract class AbstractControl {
    * the aggregate value of its parent. Its status is re-calculated based on its value and
    * its validators.
    *
-   * If the control has children, all children will be enabled.
+   * By default, if the control has children, all children will be enabled.
    *
    *  @param opts Configure options that happen when marked as untouched
-   * * If `onlySelf` is true, this will **not** mark all direct ancestors as `disabled`
+   * * `onlySelf`: When true, mark only this control. When false or not supplied,
-   * to maintain the model.
+   * marks all direct ancestors, in order to maintain the model.
-   * * If `emitEvent` is false, `statusChanges` and `valueChanges` will not emit an event.
+   * * `emitEvent`: When false, `statusChanges` and `valueChanges` will not emit an event. Otherwise,
+   * both Observables will emit a status and value event.
    */
   enable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
     (this as{status: string}).status = VALID;
@@ -505,10 +511,12 @@ export abstract class AbstractControl {
    *
    * By default, it will also update the value and validity of its ancestors.
    *
-   * @param opts Configure options that happen when the value and validity change
+   * @param opts Configuration options that control events after updating and
-   * * If `onlySelf` is true, this will **not** update all direct ancestors
+   * validity checks are applied.
-   * to maintain the model.
+   * * `onlySelf`: When true, only update this control. When false or not supplied,
-   * * If `emitEvent` is false, `statusChanges` and `valueChanges` will **not** emit an event.
+   * update all direct ancestors, in order to maintain the model.
+   * * `emitEvent`: When false, `statusChanges` and `valueChanges` will not emit an event. Otherwise,
+   * both Observables will emit a status and value event.
    */
   updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
     this._setInitialStatus();
@@ -613,12 +621,11 @@ export abstract class AbstractControl {
 
   /**
    * @description
-   * Returns error data if the control with the given path has the error specified. Otherwise
+   * Reports error data for a specific error occurring in this control or in another control.
-   * returns null or undefined.
    *
-   * @param errorCode The error code to be retrieved
+   * @param errorCode The error code for which to retrieve data
-   * @param path The path to the control. If no path is given, it checks for the error on the
+   * @param path The path to a control to check. If not supplied, checks for the error in this control.
-   * present control.
+   * @returns The error data if the control with the given path has the given error, otherwise null or undefined.
    */
   getError(errorCode: string, path?: string[]): any {
     const control = path ? this.get(path) : this;
@@ -627,12 +634,11 @@ export abstract class AbstractControl {
 
   /**
    * @description
-   * Returns true if the control with the given path has the error specified. Otherwise
+   * Reports whether the control with the given path has the error specified.
-   * returns false.
    *
-   * @param errorCode The error code to be retrieved
+   * @param errorCode The error code for which to retrieve data
-   * @param path The path to the control. If no path is given, it checks for the error on the
+   * @param path The path to a control to check. If not supplied, checks for the error in this control.
-   * present control.
+   * @returns True when the control with the given path has the error, otherwise false.
    */
   hasError(errorCode: string, path?: string[]): boolean { return !!this.getError(errorCode, path); }
 
@@ -755,8 +761,6 @@ export abstract class AbstractControl {
  * implements most of the base functionality for accessing the value, validation status, 
  * user interactions and events.
  * 
- * **npm package**: `@angular/forms`
- * 
  * @see `AbstractControl`
  * @see [Reactive Forms Guide](guide/reactive-forms)
  * @see [Usage Notes](#usage-notes)
@@ -857,16 +861,13 @@ export class FormControl extends AbstractControl {
   * @description
   * Creates a new `FormControl` instance.
   *
-  * @param formState Provides the control with an initial state in two ways:
+  * @param formState Initializes the control with an initial state value, 
-  * * with an initial value
+  * or with an object that defines the initial value, status, and options 
-  * * with an object defining the initial value, disabled status and when updates and validation are
+  * for handling updates and validation.
-  *handled.
   *
-  * @param validatorOrOpts Provides the control with one of three things:
+  * @param validatorOrOpts A synchronous validator function, or an array of 
-  * * a sync validator function
+  * such functions, or an `AbstractControlOptions` object that contains validation functions 
-  * * an array of sync validator functions
+  * and a validation trigger.
-  * * an options object containing optional validator and/or async validator functions and a
-  *validation trigger
   *
   * @param asyncValidator A single async validator or array of async validator functions
   *
@@ -886,23 +887,17 @@ export class FormControl extends AbstractControl {
 
   /**
    * @description
-   * Sets the latest value form the form control.
+   * Sets a new value for the form control.
    *
-   * @param value The latest value for the control
+   * @param value The new value for the control.
-   * @param options Configure options for emitting events when the control value changes
+   * @param options Configuration options for how the control emits events when the value changes.
+   * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
    *
-   * * If `onlySelf` is `true`, this change will only affect the validation of this `FormControl`
+   * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is false.
-   * and not its parent component. This defaults to false.
+   * * `emitEvent`: When true (the default), each change triggers a valueChanges event.
+   * * `emitModelToViewChange`: When true (the default), each change triggers an `onChange` event to update the view.
+   * * `emitViewToModelChange`: When true (the default), each change triggers an `ngModelChange` event to update the model.
    *
-   * * If `emitEvent` is `true`, this change will cause a `valueChanges` event on the `FormControl`
-   * to be emitted. This defaults to true (as it falls through to `updateValueAndValidity`).
-   *
-   * * If `emitModelToViewChange` is `true`, the view will be notified about the new value
-   * via an `onChange` event. This is the default behavior if `emitModelToViewChange` is not
-   * specified.
-   *
-   * * If `emitViewToModelChange` is `true`, an ngModelChange event will be fired to update the
-   * model.  This is the default behavior if `emitViewToModelChange` is not specified.
    */
   setValue(value: any, options: {
     onlySelf?: boolean,
@@ -925,6 +920,8 @@ export class FormControl extends AbstractControl {
    * This function is functionally the same as {@link FormControl#setValue setValue} at this level.
    * It exists for symmetry with {@link FormGroup#patchValue patchValue} on `FormGroups` and
    * `FormArrays`, where it does behave differently.
+   * 
+   * @see See `setValue` for options
    */
   patchValue(value: any, options: {
     onlySelf?: boolean,
@@ -945,18 +942,14 @@ export class FormControl extends AbstractControl {
    * * it is marked as `untouched`
    * * value is set to null
    *
-   * @param formState Provides the control with an initial state in two ways:
+   * @param formState Initializes the control with an initial state value, 
-   * * with an initial value
+   * or with an object that defines the initial value, status, and options 
-   * * with an object defining the initial value, disabled status and when updates and validation
+   * for handling updates and validation.
-   * are handled.
    *
-   * @param options Configure options for emitting events when the control value changes
+   * @param options Configuration options for emitting events when the control value changes.
    *
-   * * If `onlySelf` is `true`, this change will only affect the validation of this `FormControl`
+   * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is false.
-   * and not its parent component. This defaults to false.
+   * * `emitEvent`: When true (the default), each change triggers a valueChanges event.
-   *
-   * * If `emitEvent` is `true`, this change will cause a `valueChanges` event on the `FormControl`
-   * to be emitted. This defaults to true (as it falls through to `updateValueAndValidity`).
    *
    */
   reset(formState: any = null, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
@@ -1044,7 +1037,7 @@ export class FormControl extends AbstractControl {
  * Tracks the value and validity state of a group of `FormControl` instances.
  *
  * 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
+ * with each control name as the key.  It calculates its status by reducing the status values
  * of its children. For example, if one of the controls in a group is invalid, the entire
  * group becomes invalid.
  *
@@ -1054,8 +1047,6 @@ export class FormControl extends AbstractControl {
  * 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.
  *
- * * **npm package**: `@angular/forms`
- *
  * @usageNotes
  *
  * ### Create a form group with 2 controls
@@ -1117,14 +1108,12 @@ export class FormGroup extends AbstractControl {
   * @description
   * Creates a new `FormGroup` instance.
   *
-  * @param controls A collection of child controls. The key for each child will be the name
+  * @param controls A collection of child controls. The key for each child is the name
   * under which it is registered.
   *
-  * @param validatorOrOpts Provides the control with one of three things:
+  * @param validatorOrOpts A synchronous validator function, or an array of 
-  * * a sync validator function
+  * such functions, or an `AbstractControlOptions` object that contains validation functions 
-  * * an array of sync validator functions
+  * and a validation trigger.
-  * * an options object containing optional validator and/or async validator functions and a
-  *validation trigger
   *
   * @param asyncValidator A single async validator or array of async validator functions
   *
@@ -1146,8 +1135,8 @@ export class FormGroup extends AbstractControl {
    * @description
    * Registers a control with the group's list of controls.
    *
-   * This method does not update the value or validity of the control, so for most cases you'll want
+   * This method does not update the value or validity of the control.
-   * to use {@link FormGroup#addControl addControl} instead.
+   * Use {@link FormGroup#addControl addControl} instead.
    *
    * @param name The control name to register in the collection
    * @param control Provides the control for the given name
@@ -1163,6 +1152,8 @@ export class FormGroup extends AbstractControl {
   /**
    * @description
    * Add a control to this group.
+   * 
+   * This method also updates the value and validity of the control.
    *
    * @param name The control name to add to the collection
    * @param control Provides the control for the given name
@@ -1233,16 +1224,15 @@ export class FormGroup extends AbstractControl {
    * console.log(form.value);   // {first: 'Nancy', last: 'Drew'}
    *
    * ```
-   * @throws This method performs strict checks, so it will throw an error if you try
+   * @throws When strict checks fail, such as setting the value of a control 
-   * to set the value of a control that doesn't exist or if you exclude the
+   * that doesn't exist or if you excluding the value of a control.
-   * value of a control.
    *
-   * @param value The object that matches the structure of the group
+   * @param value The new value for the control that matches the structure of the group.
-   * @param options Configure options that happen when the value is set
+   * @param options Configuration options for how the control emits events when the value changes.
-   * * If `onlySelf` is true, this will **not** update the value and validity for all direct
+   * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
-   * ancestors
+   *
-   * to maintain the model.
+   * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is false.
-   * * If `emitEvent` is false, `statusChanges` will not emit an event.
+   * * `emitEvent`: When true (the default), each change triggers a valueChanges event.
    */
   setValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}):
       void {
@@ -1278,10 +1268,9 @@ export class FormGroup extends AbstractControl {
    *
    * @param value The object that matches the structure of the group
    * @param options Configure options that happen when the value is patched
-   * * If `onlySelf` is true, this will **not** update the value and validity for all direct
+   * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is false.
-   * ancestors
+   * * `emitEvent`: When true (the default), each change triggers a valueChanges event.
-   * to maintain the model.
+   * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
-   * * If `emitEvent` is false, `statusChanges` will not emit an event.
    */
   patchValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}):
       void {
@@ -1305,6 +1294,15 @@ export class FormGroup extends AbstractControl {
    * that matches the structure of your form, with control names as keys. The state
    * can be a standalone value or a form state object with both a value and a disabled
    * status.
+   * 
+   * @param value Initializes the control with an initial state value, 
+   * or with an object that defines the initial value, status, 
+   * and options for handling updates and validation.
+   * 
+   * @param options Configuration options that happen when the group is reset.
+   * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is false.
+   * * `emitEvent`: When true (the default), each change triggers a valueChanges event.
+   * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
    *
    * ### Reset the form group values
    *
@@ -1351,7 +1349,7 @@ export class FormGroup extends AbstractControl {
    * @description
    * The aggregate value of the `FormGroup`, including any disabled controls.
    *
-   * Retrieve all values regardless of disabled status.
+   * Retrieves all values regardless of disabled status.
    * The `value` property is the best way to get the value of the group.
    */
   getRawValue(): any {
@@ -1455,14 +1453,12 @@ export class FormGroup extends AbstractControl {
  * `FormGroup` or `FormArray` instances.
  *
  * 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
+ * It calculates its status by reducing the status values 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 `FormControl` and `FormGroup`.
  *
- * * **npm package**: `@angular/forms`
- *
  * @usageNotes
  *
  * ### Create an array of form controls
@@ -1524,11 +1520,9 @@ export class FormArray extends AbstractControl {
   * @param controls An array of child controls. Each child control will be given an index
   * wheh it is registered.
   *
-  * @param validatorOrOpts Provides the control with one of three things:
+  * @param validatorOrOpts A synchronous validator function, or an array of 
-  * * a sync validator function
+  * such functions, or an `AbstractControlOptions` object that contains validation functions 
-  * * an array of sync validator functions
+  * and a validation trigger.
-  * * an options object containing optional validator and/or async validator functions and a
-  *validation trigger
   *
   * @param asyncValidator A single async validator or array of async validator functions
   *