From 5b76f04b7f6ec6125143daf4204f309b7878e323 Mon Sep 17 00:00:00 2001 From: Brandon Roberts Date: Mon, 11 Jun 2018 15:48:35 -0500 Subject: [PATCH] docs: More edits (#24255) PR Close #24255 --- packages/forms/src/model.ts | 269 +++++++++++++++--------------------- 1 file changed, 113 insertions(+), 156 deletions(-) diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index 4be897b5e3..c0edddc4c9 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -13,7 +13,6 @@ import {AsyncValidatorFn, ValidationErrors, ValidatorFn} from './directives/vali import {toObservable} from './validators'; /** - * @description * Reports that a FormControl is valid, meaning that no errors exist in the input value. * * @see `status` @@ -21,28 +20,25 @@ import {toObservable} from './validators'; export const VALID = 'VALID'; /** - * @description * Reports that a FormControl is invalid, meaning that an error exists in the input value. - * + * * @see `status` */ export const INVALID = 'INVALID'; /** - * @description * Reports that a FormControl is pending, meaning that that async validation is occurring and * errors are not yet available for the input value. - * + * * @see `markAsPending` * @see `status` */ export const PENDING = 'PENDING'; /** - * @description * Reports that a FormControl is disabled, meaning that the control is exempt from ancestor * calculations of validity or value. - * + * * @see `markAsDisabled` * @see `status` */ @@ -95,8 +91,6 @@ function coerceToAsyncValidator( export type FormHooks = 'change' | 'blur' | 'submit'; /** - * @description - * * Interface for options provided to an `AbstractControl`. * * @experimental @@ -125,8 +119,6 @@ function isOptionsObj( /** - * @description - * * 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 @@ -156,7 +148,6 @@ export abstract class AbstractControl { private _asyncValidationSubscription: any; /** - * @description * The current value of the control. * * * For a `FormControl`, the current value. @@ -168,7 +159,6 @@ export abstract class AbstractControl { public readonly value: any; /** - * @description * Initialize the AbstractControl instance. * * @param validator The function that determines the synchronous validity of this control. @@ -178,13 +168,11 @@ export abstract class AbstractControl { constructor(public validator: ValidatorFn|null, public asyncValidator: AsyncValidatorFn|null) {} /** - * @description * The parent control. */ get parent(): FormGroup|FormArray { return this._parent; } /** - * @description * The validation status of the control. There are four possible * validation status values: * @@ -199,9 +187,8 @@ export abstract class AbstractControl { public readonly status: string; /** - * @description * A control is `valid` when its `status` is `VALID`. - * + * * @see `status` * * @returns True if the control has passed all of its validation tests, @@ -210,33 +197,30 @@ export abstract class AbstractControl { get valid(): boolean { return this.status === VALID; } /** - * @description * A control is `invalid` when its `status` is `INVALID`. - * + * * @see `status` - * + * * @returns True if this control has failed one or more of its validation checks, * false otherwise. */ get invalid(): boolean { return this.status === INVALID; } /** - * @description * A control is `pending` when its `status` is `PENDING`. - * + * * @see `status` - * + * * @returns True if this control is in the process of conducting a validation check, * false otherwise. */ get pending(): boolean { return this.status == PENDING; } /** - * @description * A control is `disabled` when its `status` is `DISABLED`. * * @see `status` - * + * * Disabled controls are exempt from validation checks and * are not included in the aggregate value of their ancestor * controls. @@ -246,11 +230,10 @@ export abstract class AbstractControl { get disabled(): boolean { return this.status === DISABLED; } /** - * @description * A control is `enabled` as long as its `status` is not `DISABLED`. - * + * * @see `status` - * + * * @returns True if the control has any status other than 'DISABLED', * false if the status is 'DISABLED'. * @@ -258,14 +241,12 @@ export abstract class AbstractControl { get enabled(): boolean { return this.status !== DISABLED; } /** - * @description * An object containing any errors generated by failing validation, * or null if there are no errors. */ public readonly errors: ValidationErrors|null; /** - * @description * A control is `pristine` if the user has not yet changed * the value in the UI. * @@ -275,7 +256,6 @@ export abstract class AbstractControl { public readonly pristine: boolean = true; /** - * @description * A control is `dirty` if the user has changed the value * in the UI. * @@ -285,7 +265,6 @@ export abstract class AbstractControl { get dirty(): boolean { return !this.pristine; } /** - * @description * True if the control is marked as `touched`. * * A control is marked `touched` once the user has triggered @@ -294,7 +273,6 @@ export abstract class AbstractControl { public readonly touched: boolean = false; /** - * @description * True if the control has not been marked as touched * * A control is `untouched` if the user has not yet triggered @@ -303,21 +281,18 @@ export abstract class AbstractControl { get untouched(): boolean { return !this.touched; } /** - * @description * A multicasting observable that emits an event every time the value of the control changes, in * the UI or programmatically. */ public readonly valueChanges: Observable; /** - * @description * A multicasting observable that emits an event every time the validation `status` of the control * recalculates. */ public readonly statusChanges: Observable; /** - * @description * Reports the update strategy of the `AbstractControl` (meaning * the event on which the control updates itself). * Possible values: `'change'` | `'blur'` | `'submit'` @@ -328,7 +303,6 @@ export abstract class AbstractControl { } /** - * @description * Sets the synchronous validators that are active on this control. Calling * this overwrites any existing sync validators. */ @@ -337,7 +311,6 @@ export abstract class AbstractControl { } /** - * @description * Sets the async validators that are active on this control. Calling this * overwrites any existing async validators. */ @@ -346,26 +319,23 @@ export abstract class AbstractControl { } /** - * @description * Empties out the sync validator list. */ clearValidators(): void { this.validator = null; } /** - * @description * Empties out the async validator list. */ clearAsyncValidators(): void { this.asyncValidator = null; } /** - * @description * Marks the control as `touched`. A control is touched by focus and * blur events that do not change the value; compare `markAsDirty`; * - * @param opts Configuration options that determine how the control events events after - * marking is applied. + * @param opts Configuration options that determine how the control propagates changes + * and emits events events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. + * marks all direct ancestors. Default is false. */ markAsTouched(opts: {onlySelf?: boolean} = {}): void { (this as{touched: boolean}).touched = true; @@ -376,16 +346,15 @@ export abstract class AbstractControl { } /** - * @description * Marks the control as `untouched`. * * If the control has any children, also marks all children as `untouched` * and recalculates the `touched` status of all parent controls. * - * @param opts Configuration options that determine how the control emits events after - * the marking is applied. + * @param opts Configuration options that determine how the control propagates changes + * and emits events after the marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. + * marks all direct ancestors. Default is false. */ markAsUntouched(opts: {onlySelf?: boolean} = {}): void { (this as{touched: boolean}).touched = false; @@ -400,14 +369,13 @@ export abstract class AbstractControl { } /** - * @description * Marks the control as `dirty`. A control becomes dirty when * the control's is changed through the UI; compare `markAsTouched`. * - * @param opts Configuration options that determine how the control emits events after - * marking is applied. + * @param opts Configuration options that determine how the control propagates changes + * and emits events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. + * marks all direct ancestors. Default is false. */ markAsDirty(opts: {onlySelf?: boolean} = {}): void { (this as{pristine: boolean}).pristine = false; @@ -418,7 +386,6 @@ export abstract class AbstractControl { } /** - * @description * Marks the control as `pristine`. * * If the control has any children, marks all children as `pristine`, @@ -428,7 +395,7 @@ export abstract class AbstractControl { * @param opts Configuration options that determine how the control emits events after * marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. + * marks all direct ancestors. Default is false.. */ markAsPristine(opts: {onlySelf?: boolean} = {}): void { (this as{pristine: boolean}).pristine = true; @@ -442,16 +409,17 @@ export abstract class AbstractControl { } /** - * @description * Marks the control as `pending`. * * A control is pending while the control performs async validation. * - * @param opts Configuration options that determine how the control propagates and + * @param opts Configuration options that determine how the control propagates changes and * emits events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. - * * `emitEvent`: When false, A `statusChanges` event is not emitted. + * marks all direct ancestors. Default is false.. + * * `emitEvent`: When true or not supplied (the default), the `statusChanges` + * observable emits an event with the latest status the control is marked pending. + * When false, no events are emitted. * */ markAsPending(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { @@ -467,7 +435,6 @@ export abstract class AbstractControl { } /** - * @description * Disables the control. This means the control is exempt from validation checks and * excluded from the aggregate value of any parent. Its status is `DISABLED`. * @@ -476,9 +443,11 @@ export abstract class AbstractControl { * @param opts Configuration options that determine how the control propagates * changes and emits events after the control is disabled. * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. - * * `emitEvent`: Set to false to prevent observables from emitting both statusChanges - * and valuesChanges events. + * marks all direct ancestors. Default is false.. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is disabled. + * When false, no events are emitted. */ disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { (this as{status: string}).status = DISABLED; @@ -497,7 +466,6 @@ export abstract class AbstractControl { } /** - * @description * Enables the control. This means the control is included in validation checks and * the aggregate value of its parent. Its status recalculates based on its value and * its validators. @@ -507,9 +475,11 @@ export abstract class AbstractControl { * @param opts Configure options that control how the control propagates changes and * emits events when marked as untouched * * `onlySelf`: When true, mark only this control. When false or not supplied, - * marks all direct ancestors, in order to maintain the model. - * * `emitEvent`: Set to false to prevent observables from emitting both statusChanges - * and valuesChanges events. + * marks all direct ancestors. Default is false.. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is enabled. + * When false, no events are emitted. */ enable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { (this as{status: string}).status = VALID; @@ -530,25 +500,21 @@ export abstract class AbstractControl { } /** - * @description * @param parent Sets the parent of the control */ setParent(parent: FormGroup|FormArray): void { this._parent = parent; } /** - * @description * Sets the value of the control. Abstract method (implemented in sub-classes). */ abstract setValue(value: any, options?: Object): void; /** - * @description * Patches the value of the control. Abstract method (implemented in sub-classes). */ abstract patchValue(value: any, options?: Object): void; /** - * @description * Resets the control. Abstract method (implemented in sub-classes). */ abstract reset(value?: any, options?: Object): void; @@ -558,12 +524,14 @@ export abstract class AbstractControl { * * By default, it also updates the value and validity of its ancestors. * - * @param opts Configuration options determine how the control is updated and emits events - * after validity checks are applied. + * @param opts Configuration options determine how the control propagates changes and emits events + * after updates and validity checks are applied. * * `onlySelf`: When true, only update this control. When false or not supplied, - * update all direct ancestors, in order to maintain the model. - * * `emitEvent`: Set to false to prevent observables from emitting both statusChanges - * and valuesChanges events. + * update all direct ancestors. Default is false.. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is updated. + * When false, no events are emitted. */ updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { this._setInitialStatus(); @@ -619,7 +587,6 @@ export abstract class AbstractControl { } /** - * @description * Sets errors on a form control when running validations manually, rather than automatically. * * Calling `setErrors` also updates the validity of the parent control. @@ -646,7 +613,6 @@ export abstract class AbstractControl { } /** - * @description * Retrieves a child control given the control's name or path. * * @param path A dot-delimited string or array of string/number values that define the path to the @@ -665,7 +631,6 @@ export abstract class AbstractControl { get(path: Array|string): AbstractControl|null { return _find(this, path, '.'); } /** - * @description * Reports error data for a specific error occurring in this control or in another control. * * @param errorCode The error code for which to retrieve data @@ -681,7 +646,6 @@ export abstract class AbstractControl { } /** - * @description * Reports whether the control with the given path has the error specified. * * @param errorCode The error code for which to retrieve data @@ -692,7 +656,6 @@ export abstract class AbstractControl { hasError(errorCode: string, path?: string[]): boolean { return !!this.getError(errorCode, path); } /** - * @description * Retrieves the top-level ancestor of this control. */ get root(): AbstractControl { @@ -802,20 +765,19 @@ export abstract class AbstractControl { } /** - * @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 - * `FormGroup` and `FormArray`. It extends the `AbstractControl` class that - * implements most of the base functionality for accessing the value, validation status, + * `FormGroup` and `FormArray`. It extends the `AbstractControl` class that + * implements most of the base functionality for accessing the value, validation status, * user interactions and events. - * + * * @see `AbstractControl` * @see [Reactive Forms Guide](guide/reactive-forms) * @see [Usage Notes](#usage-notes) - * + * * @usageNotes - * + * * ### Initializing Form Controls * * Instantiate a `FormControl`, with an initial value. @@ -825,7 +787,7 @@ export abstract class AbstractControl { * console.log(ctrl.value); // 'some value' *``` * - * The following example initializes the control with a form state object. The `value` + * The following example initializes the control with a form state object. The `value` * and `disabled` keys are required in this case. * * ```ts @@ -866,18 +828,18 @@ export abstract class AbstractControl { * ```ts * const ctrl = new FormControl('', { updateOn: 'submit' }); * ``` - * + * * ### Reset the control back to an initial value - * + * * You reset to a specific form state by passing through a standalone * value or a form state object that contains both a value and a disabled state * (these are the only two properties that cannot be calculated). * * ```ts * const ctrl = new FormControl('Nancy'); - * + * * console.log(control.value); // 'Nancy' - * + * * control.reset('Drew'); * * console.log(control.value); // 'Drew' @@ -887,10 +849,10 @@ export abstract class AbstractControl { * * ``` * const ctrl = new FormControl('Nancy'); - * + * * console.log(control.value); // 'Nancy' * console.log(this.control.status); // 'DISABLED' - * + * * control.reset({ value: 'Drew', disabled: true }); * * console.log(this.control.value); // 'Drew' @@ -908,7 +870,6 @@ export class FormControl extends AbstractControl { _pendingChange: any; /** - * @description * Creates a new `FormControl` instance. * * @param formState Initializes the control with an initial state value, @@ -936,21 +897,25 @@ export class FormControl extends AbstractControl { } /** - * @description * Sets a new value for the form control. * * @param value The new value for the control. - * @param options Configuration options that determine how the control emits events when the - * value changes. + * @param options Configuration options that determine how the control proopagates changes + * and emits events when the value changes. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * * * `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. - * * `emitModelToViewChange`: When true (the default), each change triggers an `onChange` event to + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control value is updated. + * When false, no events are emitted. + * * `emitModelToViewChange`: When true or not supplied (the default), each change triggers an + * `onChange` event to * update the view. - * * `emitViewToModelChange`: When true (the default), each change triggers an `ngModelChange` + * * `emitViewToModelChange`: When true or not supplied (the default), each change triggers an + * `ngModelChange` * event to update the model. * */ @@ -969,13 +934,12 @@ export class FormControl extends AbstractControl { } /** - * @description * Patches the value of a control. * * 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 `setValue` for options */ patchValue(value: any, options: { @@ -988,7 +952,6 @@ export class FormControl extends AbstractControl { } /** - * @description * Resets the form control, marking it `pristine` and `untouched`, and setting * the value to null. * @@ -996,12 +959,15 @@ export class FormControl extends AbstractControl { * or with an object that defines the initial value, status, and options * for handling updates and validation. * - * @param options Configuration options that determine how the control is updated and - * emits events after the value changes. + * @param options Configuration options that determine how the control propagates changes + * and emits events after the value changes. * * * `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. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is reset. + * When false, no events are emitted. * */ reset(formState: any = null, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { @@ -1028,7 +994,6 @@ export class FormControl extends AbstractControl { _allControlsDisabled(): boolean { return this.disabled; } /** - * @description * Register a listener for change events. * * @param fn The method that is called when the value changes @@ -1045,7 +1010,6 @@ export class FormControl extends AbstractControl { } /** - * @description * Register a listener for disabled events. * * @param fn The method that is called when the disabled status changes. @@ -1084,8 +1048,6 @@ export class FormControl extends AbstractControl { } /** - * @description - * * Tracks the value and validity state of a group of `FormControl` instances. * * A `FormGroup` aggregates the values of each child `FormControl` into one object, @@ -1157,7 +1119,6 @@ export class FormControl extends AbstractControl { */ export class FormGroup extends AbstractControl { /** - * @description * Creates a new `FormGroup` instance. * * @param controls A collection of child controls. The key for each child is the name @@ -1184,7 +1145,6 @@ 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. @@ -1202,7 +1162,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Add a control to this group. * * This method also updates the value and validity of the control. @@ -1217,7 +1176,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Remove a control from this group. * * @param name The control name to remove from the collection @@ -1230,7 +1188,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Replace an existing control. * * @param name The control name to replace in the collection @@ -1245,7 +1202,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Check whether there is an enabled control with the given name in the group. * * Reports false for disabled controls. If you'd like to check for existence in the group @@ -1260,7 +1216,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Sets the value of the `FormGroup`. It accepts an object that matches * the structure of the group, with control names as keys. * @@ -1282,14 +1237,17 @@ export class FormGroup extends AbstractControl { * that doesn't exist or if you excluding the value of a control. * * @param value The new value for the control that matches the structure of the group. - * @param options Configuration options that determine how the control is updated and - * emits events after the value changes. + * @param options Configuration options that determine how the control propagates changes + * and emits events after the value changes. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * * * `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. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control value is updated. + * When false, no events are emitted. */ setValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { @@ -1302,7 +1260,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Patches the value of the `FormGroup`. It accepts an object with control * names as keys, and does its best to match the values to the correct controls * in the group. @@ -1324,11 +1281,14 @@ export class FormGroup extends AbstractControl { * ``` * * @param value The object that matches the structure of the group - * @param options Configure options that determines how the control emits events after - * the value is patched + * @param options Configure options that determines how the control propagates changes and + * emits events after the value is patched * * `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. + * true. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control value is updated. + * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ @@ -1343,7 +1303,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * Resets the `FormGroup`, marks all descendants are marked `pristine` and `untouched`, and * the value of all descendants to null. * @@ -1360,7 +1319,10 @@ export class FormGroup extends AbstractControl { * and emits events 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. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is reset. + * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * @@ -1408,7 +1370,6 @@ export class FormGroup extends AbstractControl { } /** - * @description * The aggregate value of the `FormGroup`, including any disabled controls. * * Retrieves all values regardless of disabled status. @@ -1510,8 +1471,6 @@ export class FormGroup extends AbstractControl { } /** - * @description - * * Tracks the value and validity state of an array of `FormControl`, * `FormGroup` or `FormArray` instances. * @@ -1577,7 +1536,6 @@ export class FormGroup extends AbstractControl { */ export class FormArray extends AbstractControl { /** - * @description * Creates a new `FormArray` instance. * * @param controls An array of child controls. Each child control is given an index @@ -1604,7 +1562,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Get the `AbstractControl` at the given `index` in the array. * * @param index Index in the array to retrieve the control @@ -1612,7 +1569,6 @@ export class FormArray extends AbstractControl { at(index: number): AbstractControl { return this.controls[index]; } /** - * @description * Insert a new `AbstractControl` at the end of the array. * * @param control Form control to be inserted @@ -1625,7 +1581,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Insert a new `AbstractControl` at the given `index` in the array. * * @param index Index in the array to insert the control @@ -1639,7 +1594,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Remove the control at the given `index` in the array. * * @param index Index in the array to remove the control @@ -1651,7 +1605,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Replace an existing control. * * @param index Index in the array to replace the control @@ -1671,13 +1624,11 @@ export class FormArray extends AbstractControl { } /** - * @description * Length of the control array. */ get length(): number { return this.controls.length; } /** - * @description * Sets the value of the `FormArray`. It accepts an array that matches * the structure of the control. * @@ -1699,12 +1650,15 @@ export class FormArray extends AbstractControl { * ``` * * @param value Array of values for the controls - * @param options Configure options that determine how the control emits events after the - * value changes + * @param options Configure options that determine how the control propagates changes and + * emits events after the value changes * - * * `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. + * * `onlySelf`: When true, each change only affects this control, and not its parent. Default + * is false. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control value is updated. + * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ @@ -1718,7 +1672,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Patches the value of the `FormArray`. It accepts an array that matches the * structure of the control, and does its best to match the values to the correct * controls in the group. @@ -1739,12 +1692,15 @@ export class FormArray extends AbstractControl { * ``` * * @param value Array of latest values for the controls - * @param options Configure options that determine how the control emits events after the - * value changes + * @param options Configure options that determine how the control propagates changes and + * emits events after the value changes * - * * `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. + * * `onlySelf`: When true, each change only affects this control, and not its parent. Default + * is false. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control value is updated. + * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ @@ -1758,7 +1714,6 @@ export class FormArray extends AbstractControl { } /** - * @description * Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the * value of all descendants to null or null maps. * @@ -1791,12 +1746,15 @@ export class FormArray extends AbstractControl { * ``` * * @param value Array of values for the controls - * @param options Configure options that determine how the control emits events after the - * value changes + * @param options Configure options that determine how the control propagates changes and + * emits events after the value changes * - * * `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. + * * `onlySelf`: When true, each change only affects this control, and not its parent. Default + * is false. + * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and + * `valueChanges` + * observables emit events with the latest status and value when the control is reset. + * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ @@ -1810,7 +1768,6 @@ export class FormArray extends AbstractControl { } /** - * @description * The aggregate value of the array, including any disabled controls. * * Reports all values regardless of disabled status.