From e268a0579a3c2607f2fcf4ba5b03cd1313db1908 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Fri, 28 Dec 2018 11:00:50 -0800 Subject: [PATCH] docs(forms): update desc for hasError and getError (#27861) This commit adds docs for the changes made in #20211. Closes #19734. PR Close #27861 --- .../directives/abstract_control_directive.ts | 50 +++++++++++++++- packages/forms/src/model.ts | 59 +++++++++++++++---- 2 files changed, 97 insertions(+), 12 deletions(-) diff --git a/packages/forms/src/directives/abstract_control_directive.ts b/packages/forms/src/directives/abstract_control_directive.ts index 992eeb118f..65a0debe69 100644 --- a/packages/forms/src/directives/abstract_control_directive.ts +++ b/packages/forms/src/directives/abstract_control_directive.ts @@ -150,7 +150,31 @@ 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. + * + * @param errorCode The code of the error to check + * @param path A list of control names that designates how to move from the current control + * to the control that should be queried for errors. + * + * @usageNotes + * For example, for the following `FormGroup`: + * + * ``` + * form = new FormGroup({ + * address: new FormGroup({ street: new FormControl() }) + * }); + * ``` + * + * The path to the 'street' control from the root form would be 'address' -> 'street'. + * + * It can be provided to this method in one of two formats: + * + * 1. An array of string control names, e.g. `['address', 'street']` + * 1. A period-delimited list of control names in one string, e.g. `'address.street'` + * + * If no path is given, this method checks for the error on the current control. + * + * @returns whether the given error is present in the control at the given path. + * * If the control is not present, false is returned. */ hasError(errorCode: string, path?: string[]): boolean { @@ -160,7 +184,29 @@ export abstract class AbstractControlDirective { /** * @description * Reports error data for the control with the given path. - * If the control is not present, null is returned. + * + * @param errorCode The code of the error to check + * @param path A list of control names that designates how to move from the current control + * to the control that should be queried for errors. + * + * @usageNotes + * For example, for the following `FormGroup`: + * + * ``` + * form = new FormGroup({ + * address: new FormGroup({ street: new FormControl() }) + * }); + * ``` + * + * The path to the 'street' control from the root form would be 'address' -> 'street'. + * + * It can be provided to this method in one of two formats: + * + * 1. An array of string control names, e.g. `['address', 'street']` + * 1. A period-delimited list of control names in one string, e.g. `'address.street'` + * + * @returns error data for that particular error. If the control or error 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/model.ts b/packages/forms/src/model.ts index 88fed8ed55..cc649152f9 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -645,14 +645,31 @@ export abstract class AbstractControl { get(path: Array|string): AbstractControl|null { return _find(this, path, '.'); } /** - * Reports error data for a specific error occurring in this control or in another control. + * @description + * Reports error data for the control with the given path. * - * @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. + * @param errorCode The code of the error to check + * @param path A list of control names that designates how to move from the current control + * to the control that should be queried for errors. * - * @returns The error data if the control with the given path has the given error, otherwise null - * or undefined. + * @usageNotes + * For example, for the following `FormGroup`: + * + * ``` + * form = new FormGroup({ + * address: new FormGroup({ street: new FormControl() }) + * }); + * ``` + * + * The path to the 'street' control from the root form would be 'address' -> 'street'. + * + * It can be provided to this method in one of two formats: + * + * 1. An array of string control names, e.g. `['address', 'street']` + * 1. A period-delimited list of control names in one string, e.g. `'address.street'` + * + * @returns error data for that particular error. If the control or error is not present, + * null is returned. */ getError(errorCode: string, path?: string[]): any { const control = path ? this.get(path) : this; @@ -660,12 +677,34 @@ 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 - * @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. + * @param errorCode The code of the error to check + * @param path A list of control names that designates how to move from the current control + * to the control that should be queried for errors. + * + * @usageNotes + * For example, for the following `FormGroup`: + * + * ``` + * form = new FormGroup({ + * address: new FormGroup({ street: new FormControl() }) + * }); + * ``` + * + * The path to the 'street' control from the root form would be 'address' -> 'street'. + * + * It can be provided to this method in one of two formats: + * + * 1. An array of string control names, e.g. `['address', 'street']` + * 1. A period-delimited list of control names in one string, e.g. `'address.street'` + * + * If no path is given, this method checks for the error on the current control. + * + * @returns whether the given error is present in the control at the given path. + * + * If the control is not present, false is returned. */ hasError(errorCode: string, path?: string[]): boolean { return !!this.getError(errorCode, path); }