docs(forms): update desc for hasError and getError (#27861)

This commit adds docs for the changes made in #20211.

Closes #19734.

PR Close #27861

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;

packages/forms/src/model.ts

@@ -645,14 +645,31 @@ export abstract class AbstractControl {
   get(path: Array<string|number>|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 errorCode The code of the error to check
-   * @param path The path to a control to check. If not supplied, checks for the error in this
+   * @param path A list of control names that designates how to move from the current control
-   * 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
+   * @usageNotes
-   * or undefined.
+   * 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 errorCode The code of the error to check
-   * @param path The path to a control to check. If not supplied, checks for the error in this
+   * @param path A list of control names that designates how to move from the current control
-   * control.
+   * to the control that should be queried for errors.
-   * @returns True when the control with the given path has the error, otherwise false.
+   *
+   * @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); }