diff --git a/packages/forms/src/directives/abstract_control_directive.ts b/packages/forms/src/directives/abstract_control_directive.ts index 1a682ec473..d0884eeeb4 100644 --- a/packages/forms/src/directives/abstract_control_directive.ts +++ b/packages/forms/src/directives/abstract_control_directive.ts @@ -14,7 +14,7 @@ import {ValidationErrors} from './validators'; * @description * Base class for control directives. * - * This class is only used internally in the `FormsModule`. + * This class is only used internally in the `ReactiveFormsModule` and the `FormsModule`. * */ export abstract class AbstractControlDirective { @@ -28,114 +28,94 @@ export abstract class AbstractControlDirective { /** * @description - * The value of the control. - * - * @returns The value of the control if it is present, otherwise null. + * Reports the value of the control if it is present, otherwise null. */ get value(): any { return this.control ? this.control.value : null; } /** * @description - * Reports that the control is valid, meaning that no errors exist in the input value. - * - * @returns The control's valid state if the control is present, otherwise null. + * Reports whether the control is valid. A control is considered valid if no + * validation errors exist with the current value. + * If the control is not present, null is returned. */ get valid(): boolean|null { return this.control ? this.control.valid : null; } /** * @description - * Reports that the control is invalid, meaning that an error exists in the input value. - * - * @returns The control's invalid state if the control is present, otherwise null. + * Reports whether the control is invalid, meaning that an error exists in the input value. + * If the control is not present, null is returned. */ get invalid(): boolean|null { return this.control ? this.control.invalid : null; } /** * @description - * Reports that a control is pending, meaning that that async validation is occurring and - * errors are not yet available for the input value. - * - * @returns The control's pending state if the control is present, otherwise null. + * Reports whether a control is pending, meaning that that async validation is occurring and + * errors are not yet available for the input value. If the control is not present, null is + * returned. */ get pending(): boolean|null { return this.control ? this.control.pending : null; } /** * @description - * Reports that the control is disabled, meaning that the control is exempt from ancestor - * calculations of validity or value. - * - * @returns The control's disabled state if the control is present, otherwise null. + * Reports whether the control is disabled, meaning that the control is disabled + * in the UI and is exempt from validation checks and excluded from aggregate + * values of ancestor controls. If the control is not present, null is returned. */ get disabled(): boolean|null { return this.control ? this.control.disabled : null; } /** * @description - * Reports that the control is enabled, meaning that the control is included in ancestor - * calculations of validity or value. - * - * @returns The control's enabled state if the control is present, otherwise null. + * Reports whether the control is enabled, meaning that the control is included in ancestor + * calculations of validity or value. If the control is not present, null is returned. */ get enabled(): boolean|null { return this.control ? this.control.enabled : null; } /** * @description - * Reports the FormControl validation errors. - * - * @returns The control's validation errors if the control is present, otherwise null. + * Reports the control's validation errors. If the control is not present, null is returned. */ get errors(): ValidationErrors|null { return this.control ? this.control.errors : null; } /** * @description - * Reports that the control is pristine, meaning that the control the user has not yet changed - * the value in the UI. - * - * @returns The control's pristine state if the control is present, otherwise null. + * Reports whether the control is pristine, meaning that the user has not yet changed + * the value in the UI. If the control is not present, null is returned. */ get pristine(): boolean|null { return this.control ? this.control.pristine : null; } /** * @description - * Reports that the control is dirty, meaning that the control the user has changed - * the value in the UI. - * - * @returns The control's dirty state if the control is present, otherwise null. + * Reports whether the control is dirty, meaning that the user has changed + * the value in the UI. If the control is not present, null is returned. */ get dirty(): boolean|null { return this.control ? this.control.dirty : null; } /** * @description - * Reports that the control is touched, meaning that the the user has triggered - * a `blur` event on it. - * - * @returns The control's touched state if the control is present, otherwise null. + * Reports whether the control is touched, meaning that the user has triggered + * a `blur` event on it. If the control is not present, null is returned. */ get touched(): boolean|null { return this.control ? this.control.touched : null; } /** * @description - * Reports that a FormControl is touched, meaning that the the user has triggered - * a `blur` event on it. - * - * @returns The control's touched state if the control is present, otherwise null. + * Reports the validation status of the control. Possible values include: + * 'VALID', 'INVALID', 'DISABLED', and 'PENDING'. + * If the control is not present, null is returned. */ get status(): string|null { return this.control ? this.control.status : null; } /** * @description - * Reports that a FormControl is untouched, meaning that the the user has not yet triggered - * a `blur` event on it. - * - * @returns The control's untouched state if the control is present, otherwise null. + * Reports whether the control is untouched, meaning that the user has not yet triggered + * a `blur` event on it. If the control is not present, null is returned. */ get untouched(): boolean|null { return this.control ? this.control.untouched : null; } /** * @description - * Reports the observable of status changes for the control. - * - * @returns An observable that emits every time the validation status of the control - * is re-calculated if the control is present, otherwise null. + * Returns a multicasting observable that emits a validation status whenever it is + * calculated for the control. If the control is not present, null is returned. */ get statusChanges(): Observable|null { return this.control ? this.control.statusChanges : null; @@ -143,10 +123,9 @@ export abstract class AbstractControlDirective { /** * @description - * Reports the observable of value changes for the control. - * - * @returns An observable that emits every time the value of the control - * changes in the UI or programmatically if the control is present, otherwise null. + * Returns a multicasting observable of value changes for the control that emits every time the + * value of the control changes in the UI or programmatically. + * If the control is not present, null is returned. */ get valueChanges(): Observable|null { return this.control ? this.control.valueChanges : null; @@ -154,16 +133,14 @@ export abstract class AbstractControlDirective { /** * @description - * Reports an array that represents the path from the top-level form to this control. + * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. - * */ get path(): string[]|null { return null; } /** * @description - * Resets the control with the provided value if the control is present - * + * Resets the control with the provided value if the control is present. */ reset(value: any = undefined): void { if (this.control) this.control.reset(value); @@ -173,8 +150,7 @@ export abstract class AbstractControlDirective { * @description * Reports whether the control with the given path has the error specified. * If no path is given, it checks for the error on the present control. - * - * @returns True if the control is present and has the error specified, otherwise false + * If the control is not present, false is returned. */ hasError(errorCode: string, path?: string[]): boolean { return this.control ? this.control.hasError(errorCode, path) : false; @@ -182,10 +158,8 @@ export abstract class AbstractControlDirective { /** * @description - * Reports error data for the control with the given path. Otherwise - * returns null or undefined. - * - * @returns The control's error if the control is present, otherwise null + * Reports error data for the control with the given path. + * If the control is not present, null is returned. */ getError(errorCode: string, path?: string[]): any { return this.control ? this.control.getError(errorCode, path) : null; diff --git a/packages/forms/src/directives/abstract_form_group_directive.ts b/packages/forms/src/directives/abstract_form_group_directive.ts index 3598a29473..7b423588be 100644 --- a/packages/forms/src/directives/abstract_form_group_directive.ts +++ b/packages/forms/src/directives/abstract_form_group_directive.ts @@ -52,7 +52,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn /** * @description - * The callback method triggered on the instance after the inputs are set. + * An internal callback method triggered on the instance after the inputs are set. * Registers the group with its parent group. */ ngOnInit(): void { @@ -62,7 +62,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn /** * @description - * The callback method trigger before the instance is destroyed. + * An internal callback method triggered before the instance is destroyed. * Removes the group from its parent group. */ ngOnDestroy(): void { @@ -73,33 +73,31 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn /** * @description - * Reports the `FormGroup` bound to this directive from its parent + * The `FormGroup` bound to this directive. */ get control(): FormGroup { return this.formDirective !.getFormGroup(this); } /** * @description - * Reports the path to this group + * The path to this group from the top-level directive. */ get path(): string[] { return controlPath(this.name, this._parent); } /** * @description - * Reports the parent form for this group - * - * @returns The parent form if present, otherwise null. + * The top-level directive for this group if present, otherwise null. */ get formDirective(): Form|null { return this._parent ? this._parent.formDirective : null; } /** * @description - * Reports the synchronous validators registered with this group + * The synchronous validators registered with this group. */ get validator(): ValidatorFn|null { return composeValidators(this._validators); } /** * @description - * Reports the async validators registered with this group + * The async validators registered with this group. */ get asyncValidator(): AsyncValidatorFn|null { return composeAsyncValidators(this._asyncValidators); diff --git a/packages/forms/src/directives/control_container.ts b/packages/forms/src/directives/control_container.ts index a6529386a9..747a6b11ca 100644 --- a/packages/forms/src/directives/control_container.ts +++ b/packages/forms/src/directives/control_container.ts @@ -25,13 +25,13 @@ export abstract class ControlContainer extends AbstractControlDirective { /** * @description - * Reports the parent form for the control + * The top-level form directive for the control. */ get formDirective(): Form|null { return null; } /** * @description - * Reports the path to this group + * The path to this group. */ get path(): string[]|null { return null; } } diff --git a/packages/forms/src/directives/control_value_accessor.ts b/packages/forms/src/directives/control_value_accessor.ts index 30f3d90147..aa90ecb045 100644 --- a/packages/forms/src/directives/control_value_accessor.ts +++ b/packages/forms/src/directives/control_value_accessor.ts @@ -55,7 +55,7 @@ export interface ControlValueAccessor { * * The following example stores the provided function as an internal method. * - * ```typescript + * ```ts * registerOnChange(fn: (_: any) => void): void { * this._onChange = fn; * } @@ -64,7 +64,7 @@ export interface ControlValueAccessor { * When the value changes in the UI, call the registered * function to allow the forms API to update itself: * - * ```typescript + * ```ts * host: { * (change): '_onChange($event.target.value)' * } @@ -76,10 +76,8 @@ export interface ControlValueAccessor { /** * @description - * Registers a callback function that is called when the control receives a blur event. - * - * This is called by the forms API on initialization so it can update the form model - * on blur. + * Registers a callback function is called by the forms API on initialization + * to update the form model on blur. * * When implementing `registerOnTouched` in your own value accessor, save the given * function so your class calls it when the control should be considered @@ -87,7 +85,7 @@ export interface ControlValueAccessor { * * ### Store the callback function * - * The folliwing example stores the provided function as an internal method. + * The following example stores the provided function as an internal method. * * ```ts * registerOnTouched(fn: any): void { @@ -95,7 +93,7 @@ export interface ControlValueAccessor { * } * ``` * - * On blur (or equivalent), your class calls the registered function to allow + * On blur (or equivalent), your class should call the registered function to allow * the forms API to update itself: * * ```ts @@ -110,8 +108,8 @@ export interface ControlValueAccessor { /** * @description - * Registers a callback function that is called when the control status is disabled or - * re-enabled. Depending on the status, it enables or disables the + * Function that is called by the forms API when the control status changes to + * or from 'DISABLED'. Depending on the status, it enables or disables the * appropriate DOM element. * * The following is an example of writing the disabled property to a native DOM element: diff --git a/packages/forms/src/directives/form_interface.ts b/packages/forms/src/directives/form_interface.ts index 1a52b623cc..f58e60ddfd 100644 --- a/packages/forms/src/directives/form_interface.ts +++ b/packages/forms/src/directives/form_interface.ts @@ -17,14 +17,14 @@ import {NgControl} from './ng_control'; * @description * An interface implemented by `FormGroupDirective` and `NgForm` directives. * - * Only used by the `FormsModule`. + * Only used by the `ReactiveFormsModule` and `FormsModule`. */ export interface Form { /** * @description * Add a control to this form. * - * @param dir The control to add to the form + * @param dir The control directive to add to the form. */ addControl(dir: NgControl): void; @@ -32,15 +32,15 @@ export interface Form { * @description * Remove a control from this form. * - * @param dir: The control to remove from the form + * @param dir: The control directive to remove from the form. */ removeControl(dir: NgControl): void; /** * @description - * Reports the `FormControl` associated with the provided `NgControl`. + * The control directive from which to get the `FormControl`. * - * @param dir: The form control instance + * @param dir: The control directive. */ getControl(dir: NgControl): FormControl; @@ -48,7 +48,7 @@ export interface Form { * @description * Add a group of controls to this form. * - * @param dir: The control group to remove + * @param dir: The control group directive to add. */ addFormGroup(dir: AbstractFormGroupDirective): void; @@ -56,15 +56,15 @@ export interface Form { * @description * Remove a group of controls to this form. * - * @param dir: The control group to remove + * @param dir: The control group directive to remove. */ removeFormGroup(dir: AbstractFormGroupDirective): void; /** * @description - * Reports the form group for the provided control + * The `FormGroup` associated with a particular `AbstractFormGroupDirective`. * - * @param dir: The form group to query + * @param dir: The form group directive from which to get the `FormGroup`. */ getFormGroup(dir: AbstractFormGroupDirective): FormGroup; @@ -72,8 +72,8 @@ export interface Form { * @description * Update the model for a particular control with a new value. * - * @param dir: The control to update - * @param value: The new value for the control + * @param dir: The control directive to update. + * @param value: The new value for the control. */ updateModel(dir: NgControl, value: any): void; } diff --git a/packages/forms/src/directives/ng_control.ts b/packages/forms/src/directives/ng_control.ts index 4becf75adb..2affcbe0fa 100644 --- a/packages/forms/src/directives/ng_control.ts +++ b/packages/forms/src/directives/ng_control.ts @@ -18,13 +18,14 @@ function unimplemented(): any { /** * @description - * A base class that all control directives extend. It binds a `FormControl` object to a - * DOM element and is only used internally by Angular forms. + * A base class that all control `FormControl`-based directives extend. It binds a `FormControl` + * object to a DOM element. */ export abstract class NgControl extends AbstractControlDirective { /** * @description - * The parent form for the control + * The parent form for the control. + * * @internal */ _parent: ControlContainer|null = null; diff --git a/packages/forms/src/directives/validators.ts b/packages/forms/src/directives/validators.ts index 5b615d0f1b..c9727435a5 100644 --- a/packages/forms/src/directives/validators.ts +++ b/packages/forms/src/directives/validators.ts @@ -36,11 +36,11 @@ export type ValidationErrors = { * * ```typescript * @Directive({ - * selector: '[custom-validator]', + * selector: '[customValidator]', * providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}] * }) * class CustomValidatorDirective implements Validator { - * validate(c: AbstractControl): {[key: string]: any} { + * validate(c: AbstractControl): ValidationErrors|null { * return {'custom': true}; * } * } @@ -49,7 +49,7 @@ export type ValidationErrors = { export interface Validator { /** * @description - * Method that performs synchronous verification against the provided control. + * Method that performs synchronous validation against the provided control. * * @param c The control to validate against. * @@ -82,12 +82,12 @@ export interface Validator { * import { of as observableOf } from 'rxjs'; * * @Directive({ - * selector: '[custom-async-validator]', + * selector: '[customAsyncValidator]', * providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi: * true}] * }) * class CustomAsyncValidatorDirective implements AsyncValidator { - * validate(c: AbstractControl): Observable<{[key: string]: any}> { + * validate(c: AbstractControl): Observable { * return observableOf({'custom': true}); * } * } @@ -98,7 +98,7 @@ export interface Validator { export interface AsyncValidator extends Validator { /** * @description - * Method that performs async verification against the provided control. + * Method that performs async validation against the provided control. * * @param c The control to validate against. *