From 43e61c25e1d0c634a6d6ba49fff02cbfddddeaa1 Mon Sep 17 00:00:00 2001 From: Brandon Roberts Date: Wed, 6 Jun 2018 12:17:30 -0500 Subject: [PATCH] docs(docs-infra): Update with review changes (#24255) PR Close #24255 --- packages/forms/src/model.ts | 256 ++++++++++++++++++------------------ 1 file changed, 125 insertions(+), 131 deletions(-) diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index a94e12839a..775a2d97d1 100644 --- a/packages/forms/src/model.ts +++ b/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 - * * **INVALID**: control has failed at least one validation check - * * **PENDING**: control is in the midst of conducting a validation check - * * **DISABLED**: control is exempt from validation checks + * * **VALID**: This control has passed all validation checks. + * * **INVALID**: This control has failed at least one validation check. + * * **PENDING**: This control is in the midst of conducting a validation check. + * * **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 - * validation checks. + * True if the control has passed all of its validation tests, + * 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 - * at least one of its validation checks. + * True if this control has failed one or more 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 - * middle of conducting a validation check. + * 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`. - * + * + * 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 - * `PENDING`. + * + * True if the control has any status other than 'DISABLED', + * false if the status is 'DISABLED'. + * */ get enabled(): boolean { return this.status !== DISABLED; } /** * @description - * Returns any errors generated by failing validation. If there - * are no errors, it will return null. + * An object containing any errors generated by failing validation, + * 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 - * **not** mark it dirty. + * True if the user has not yet changed the value in the UI; compare `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 - * **not** mark it dirty. + * True if the user has changed the value of this control in the UI; compare `pristine`. + * 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; /** * @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; /** * @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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `touched` - * to maintain the model. Defaults to false + * @param opts Configuration options that how 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. */ 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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `touched` - * to maintain the model. Defaults to false + * @param opts Configuration options that how 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. */ 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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `dirty` to maintain - * to maintain the model. Defaults to false + * @param opts Configuration options that how 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. */ 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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `pristine` - * to maintain the model. Defaults to false + * @param opts Configuration options that how 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. */ 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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `untouched` - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` will not emit an event. + * @param opts Configuration options that how 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, `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 - * * If `onlySelf` is true, this will **not** mark all direct ancestors as `disabled` - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` and `valueChanges` will not emit an event. + * @param opts Configuration options that how 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, `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` - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` and `valueChanges` will not emit an event. + * * `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, `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 - * * If `onlySelf` is true, this will **not** update all direct ancestors - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` and `valueChanges` will **not** emit an event. + * @param opts Configuration options that control events after updating 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`: 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 - * returns null or undefined. + * Reports error data for a specific error occurring in this control or in another control. * - * @param errorCode The error code to be retrieved - * @param path The path to the control. If no path is given, it checks for the error on the - * present control. + * @param errorCode The error code for which to retrieve data + * @param path The path to a control to check. If not supplied, checks for the error in this 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 - * returns false. + * Reports whether the control with the given path has the error specified. * - * @param errorCode The error code to be retrieved - * @param path The path to the control. If no path is given, it checks for the error on the - * present control. + * @param errorCode The error code for which to retrieve data + * @param path The path to a control to check. If not supplied, checks for the error in this 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: - * * with an initial value - * * with an object defining the initial value, disabled status and when updates and validation are - *handled. + * @param formState 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 validatorOrOpts Provides the control with one of three things: - * * a sync validator function - * * an array of sync validator functions - * * an options object containing optional validator and/or async validator functions and a - *validation trigger + * @param validatorOrOpts A synchronous validator function, or an array of + * such functions, or an `AbstractControlOptions` object that contains validation 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 options Configure options for emitting events when the control value changes + * @param value The new value for the control. + * @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` - * and not its parent component. This defaults to false. + * * `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 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: - * * with an initial value - * * with an object defining the initial value, disabled status and when updates and validation - * are handled. + * @param formState 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 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` - * and not its parent component. This defaults to false. - * - * * 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`). + * * `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. * */ 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: - * * a sync validator function - * * an array of sync validator functions - * * an options object containing optional validator and/or async validator functions and a - *validation trigger + * @param validatorOrOpts A synchronous validator function, or an array of + * such functions, or an `AbstractControlOptions` object that contains validation 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 - * to use {@link FormGroup#addControl addControl} instead. + * This method does not update the value or validity of the control. + * 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 - * to set the value of a control that doesn't exist or if you exclude the - * value of a control. + * @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. * - * @param value The object that matches the structure of the group - * @param options Configure options that happen when the value is set - * * If `onlySelf` is true, this will **not** update the value and validity for all direct - * ancestors - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` will not emit an event. + * @param value The new value for the control that matches the structure of the group. + * @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. + * + * * `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. */ 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 - * ancestors - * to maintain the model. - * * If `emitEvent` is false, `statusChanges` will not emit an event. + * * `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. */ 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: - * * a sync validator function - * * an array of sync validator functions - * * an options object containing optional validator and/or async validator functions and a - *validation trigger + * @param validatorOrOpts A synchronous validator function, or an array of + * such functions, or an `AbstractControlOptions` object that contains validation functions + * and a validation trigger. * * @param asyncValidator A single async validator or array of async validator functions *