docs(harnesses): ensure all harnesses have complete and correct docs (#17723)

Author: mmalerba

src/cdk/testing/component-harness.ts

@@ -384,10 +384,11 @@ export interface ComponentHarnessConstructor<T extends ComponentHarness> {
   hostSelector: string;
 }
 
+/** A set of criteria that can be used to filter a list of `ComponentHarness` instances. */
 export interface BaseHarnessFilters {
-  /** Only find component instances whose host element matches the given selector. */
+  /** Only find instances whose host element matches the given selector. */
   selector?: string;
-  /** Only find component instances that are nested under an element with the given selector. */
+  /** Only find instances that are nested under an element with the given selector. */
   ancestor?: string;
 }
 

src/material/autocomplete/testing/autocomplete-harness-filters.ts

@@ -8,6 +8,8 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
+/** A set of criteria that can be used to filter a list of `MatAutocompleteHarness` instances. */
 export interface AutocompleteHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose associated input element matches the given value. */
   value?: string | RegExp;
 }

src/material/autocomplete/testing/autocomplete-harness.ts

@@ -24,13 +24,13 @@ export class MatAutocompleteHarness extends ComponentHarness {
   private _documentRootLocator = this.documentRootLocatorFactory();
   private _optionalPanel = this._documentRootLocator.locatorForOptional(PANEL_SELECTOR);
 
+  /** The selector for the host element of a `MatAutocomplete` instance. */
   static hostSelector = '.mat-autocomplete-trigger';
 
   /**
-   * Gets a `HarnessPredicate` that can be used to search for an autocomplete with
-   * specific attributes.
-   * @param options Options for narrowing the search:
-   *   - `name` finds an autocomplete with a specific name.
+   * Gets a `HarnessPredicate` that can be used to search for a `MatAutocompleteHarness` that meets
+   * certain criteria.
+   * @param options Options for filtering which autocomplete instances are considered a match.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: AutocompleteHarnessFilters = {}): HarnessPredicate<MatAutocompleteHarness> {
@@ -44,18 +44,18 @@ export class MatAutocompleteHarness extends ComponentHarness {
     return (await this.host()).getProperty('value');
   }
 
-  /** Gets a boolean promise indicating if the autocomplete input is disabled. */
+  /** Whether the autocomplete input is disabled. */
   async isDisabled(): Promise<boolean> {
     const disabled = (await this.host()).getAttribute('disabled');
     return coerceBooleanProperty(await disabled);
   }
 
-  /** Focuses the input and returns a void promise that indicates when the action is complete. */
+  /** Focuses the autocomplete input. */
   async focus(): Promise<void> {
     return (await this.host()).focus();
   }
 
-  /** Blurs the input and returns a void promise that indicates when the action is complete. */
+  /** Blurs the autocomplete input. */
   async blur(): Promise<void> {
     return (await this.host()).blur();
   }
@@ -70,7 +70,7 @@ export class MatAutocompleteHarness extends ComponentHarness {
     return this._documentRootLocator.locatorForAll(MatAutocompleteOptionHarness.with(filters))();
   }
 
-  /** Gets the groups of options inside the panel. */
+  /** Gets the option groups inside the autocomplete panel. */
   async getOptionGroups(filters: OptionGroupHarnessFilters = {}):
       Promise<MatAutocompleteOptionGroupHarness[]> {
     return this._documentRootLocator.locatorForAll(
@@ -87,7 +87,7 @@ export class MatAutocompleteHarness extends ComponentHarness {
     await options[0].select();
   }
 
-  /** Gets whether the autocomplete is open. */
+  /** Whether the autocomplete is open. */
   async isOpen(): Promise<boolean> {
     const panel = await this._optionalPanel();
     return !!panel && await panel.hasClass('mat-autocomplete-visible');

src/material/autocomplete/testing/option-harness.ts

@@ -11,18 +11,34 @@ import {ComponentHarness, HarnessPredicate, BaseHarnessFilters} from '@angular/c
 // TODO(crisbeto): combine these with the ones in `mat-select`
 // and expand to cover all states once we have experimental/core.
 
+/**
+ * A set of criteria that can be used to filter a list of `MatAutocompleteOptionHarness` instances
+ */
 export interface OptionHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose text matches the given value. */
   text?: string | RegExp;
 }
 
+/**
+ * A set of criteria that can be used to filter a list of `MatAutocompleteOptionGroupHarness`
+ * instances.
+ */
 export interface OptionGroupHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose label text matches the given value. */
   labelText?: string | RegExp;
 }
 
 /** Harness for interacting with a the `mat-option` for a `mat-autocomplete` in tests. */
 export class MatAutocompleteOptionHarness extends ComponentHarness {
+  /** The selector for the host element of an autocomplete `MatOption` instance. */
   static hostSelector = '.mat-autocomplete-panel .mat-option';
 
+  /**
+   * Gets a `HarnessPredicate` that can be used to search for a `MatAutocompleteOptionHarness` that
+   * meets certain criteria.
+   * @param options Options for filtering which option instances are considered a match.
+   * @return a `HarnessPredicate` configured with the given options.
+   */
   static with(options: OptionHarnessFilters = {}) {
     return new HarnessPredicate(MatAutocompleteOptionHarness, options)
         .addOption('text', options.text,
@@ -34,7 +50,7 @@ export class MatAutocompleteOptionHarness extends ComponentHarness {
     return (await this.host()).click();
   }
 
-  /** Gets a promise for the option's label text. */
+  /** Gets the option's label text. */
   async getText(): Promise<string> {
     return (await this.host()).text();
   }
@@ -43,15 +59,23 @@ export class MatAutocompleteOptionHarness extends ComponentHarness {
 /** Harness for interacting with a the `mat-optgroup` for a `mat-autocomplete` in tests. */
 export class MatAutocompleteOptionGroupHarness extends ComponentHarness {
   private _label = this.locatorFor('.mat-optgroup-label');
+
+  /** The selector for the host element of an autocomplete `MatOptionGroup` instance. */
   static hostSelector = '.mat-autocomplete-panel .mat-optgroup';
 
+  /**
+   * Gets a `HarnessPredicate` that can be used to search for a `MatAutocompleteOptionGroupHarness`
+   * that meets certain criteria.
+   * @param options Options for filtering which option group instances are considered a match.
+   * @return a `HarnessPredicate` configured with the given options.
+   */
   static with(options: OptionGroupHarnessFilters = {}) {
     return new HarnessPredicate(MatAutocompleteOptionGroupHarness, options)
         .addOption('labelText', options.labelText,
             (harness, label) => HarnessPredicate.stringMatches(harness.getLabelText(), label));
   }
 
-  /** Gets a promise for the option group's label text. */
+  /** Gets the option group's label text. */
   async getLabelText(): Promise<string> {
     return (await this._label()).text();
   }

src/material/button/testing/button-harness-filters.ts

@@ -8,6 +8,8 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
+/** A set of criteria that can be used to filter a list of `MatButtonHarness` instances. */
 export interface ButtonHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose text matches the given value. */
   text?: string | RegExp;
 }

src/material/button/testing/button-harness.ts

@@ -14,6 +14,7 @@ import {ButtonHarnessFilters} from './button-harness-filters';
 /** Harness for interacting with a standard mat-button in tests. */
 export class MatButtonHarness extends ComponentHarness {
   // TODO(jelbourn) use a single class, like `.mat-button-base`
+  /** The selector for the host element of a `MatButton` instance. */
   static hostSelector = [
     '[mat-button]',
     '[mat-raised-button]',
@@ -25,10 +26,9 @@ export class MatButtonHarness extends ComponentHarness {
   ].join(',');
 
   /**
-   * Gets a `HarnessPredicate` that can be used to search for a button with specific attributes.
-   * @param options Options for narrowing the search:
-   *   - `selector` finds a button whose host element matches the given selector.
-   *   - `text` finds a button with specific text content.
+   * Gets a `HarnessPredicate` that can be used to search for a `MatButtonHarness` that meets
+   * certain criteria.
+   * @param options Options for filtering which button instances are considered a match.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: ButtonHarnessFilters = {}): HarnessPredicate<MatButtonHarness> {
@@ -42,23 +42,23 @@ export class MatButtonHarness extends ComponentHarness {
     return (await this.host()).click();
   }
 
-  /** Gets a boolean promise indicating if the button is disabled. */
+  /** Whether the button is disabled. */
   async isDisabled(): Promise<boolean> {
     const disabled = (await this.host()).getAttribute('disabled');
     return coerceBooleanProperty(await disabled);
   }
 
-  /** Gets a promise for the button's label text. */
+  /** Gets the button's label text. */
   async getText(): Promise<string> {
     return (await this.host()).text();
   }
 
-  /** Focuses the button and returns a void promise that indicates when the action is complete. */
+  /** Focuses the button. */
   async focus(): Promise<void> {
     return (await this.host()).focus();
   }
 
-  /** Blurs the button and returns a void promise that indicates when the action is complete. */
+  /** Blurs the button. */
   async blur(): Promise<void> {
     return (await this.host()).blur();
   }

src/material/checkbox/testing/checkbox-harness-filters.ts

@@ -8,7 +8,10 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
+/** A set of criteria that can be used to filter a list of `MatCheckboxHarness` instances. */
 export interface CheckboxHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose label matches the given value. */
   label?: string | RegExp;
+  /** Only find instances whose name attribute is the given value. */
   name?: string;
 }

src/material/checkbox/testing/checkbox-harness.ts

@@ -12,14 +12,13 @@ import {CheckboxHarnessFilters} from './checkbox-harness-filters';
 
 /** Harness for interacting with a standard mat-checkbox in tests. */
 export class MatCheckboxHarness extends ComponentHarness {
+  /** The selector for the host element of a `MatCheckbox` instance. */
   static hostSelector = 'mat-checkbox';
 
   /**
-   * Gets a `HarnessPredicate` that can be used to search for a checkbox with specific attributes.
-   * @param options Options for narrowing the search:
-   *   - `selector` finds a checkbox whose host element matches the given selector.
-   *   - `label` finds a checkbox with specific label text.
-   *   - `name` finds a checkbox with specific name.
+   * Gets a `HarnessPredicate` that can be used to search for a `MatCheckboxHarness` that meets
+   * certain criteria.
+   * @param options Options for filtering which checkbox instances are considered a match.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: CheckboxHarnessFilters = {}): HarnessPredicate<MatCheckboxHarness> {
@@ -37,74 +36,73 @@ export class MatCheckboxHarness extends ComponentHarness {
   private _input = this.locatorFor('input');
   private _inputContainer = this.locatorFor('.mat-checkbox-inner-container');
 
-  /** Gets a boolean promise indicating if the checkbox is checked. */
+  /** Whether the checkbox is checked. */
   async isChecked(): Promise<boolean> {
     const checked = (await this._input()).getProperty('checked');
     return coerceBooleanProperty(await checked);
   }
 
-  /** Gets a boolean promise indicating if the checkbox is in an indeterminate state. */
+  /** Whether the checkbox is in an indeterminate state. */
   async isIndeterminate(): Promise<boolean> {
     const indeterminate = (await this._input()).getProperty('indeterminate');
     return coerceBooleanProperty(await indeterminate);
   }
 
-  /** Gets a boolean promise indicating if the checkbox is disabled. */
+  /** Whether the checkbox is disabled. */
   async isDisabled(): Promise<boolean> {
     const disabled = (await this._input()).getAttribute('disabled');
     return coerceBooleanProperty(await disabled);
   }
 
-  /** Gets a boolean promise indicating if the checkbox is required. */
+  /** Whether the checkbox is required. */
   async isRequired(): Promise<boolean> {
     const required = (await this._input()).getProperty('required');
     return coerceBooleanProperty(await required);
   }
 
-  /** Gets a boolean promise indicating if the checkbox is valid. */
+  /** Whether the checkbox is valid. */
   async isValid(): Promise<boolean> {
     const invalid = (await this.host()).hasClass('ng-invalid');
     return !(await invalid);
   }
 
-  /** Gets a promise for the checkbox's name. */
+  /** Gets the checkbox's name. */
   async getName(): Promise<string|null> {
     return (await this._input()).getAttribute('name');
   }
 
-  /** Gets a promise for the checkbox's value. */
+  /** Gets the checkbox's value. */
   async getValue(): Promise<string|null> {
     return (await this._input()).getProperty('value');
   }
 
-  /** Gets a promise for the checkbox's aria-label. */
+  /** Gets the checkbox's aria-label. */
   async getAriaLabel(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-label');
   }
 
-  /** Gets a promise for the checkbox's aria-labelledby. */
+  /** Gets the checkbox's aria-labelledby. */
   async getAriaLabelledby(): Promise<string|null> {
     return (await this._input()).getAttribute('aria-labelledby');
   }
 
-  /** Gets a promise for the checkbox's label text. */
+  /** Gets the checkbox's label text. */
   async getLabelText(): Promise<string> {
     return (await this._label()).text();
   }
 
-  /** Focuses the checkbox and returns a void promise that indicates when the action is complete. */
+  /** Focuses the checkbox. */
   async focus(): Promise<void> {
     return (await this._input()).focus();
   }
 
-  /** Blurs the checkbox and returns a void promise that indicates when the action is complete. */
+  /** Blurs the checkbox. */
   async blur(): Promise<void> {
     return (await this._input()).blur();
   }
 
   /**
-   * Toggle the checked state of the checkbox and returns a void promise that indicates when the
-   * action is complete.
+   * Toggles the checked state of the checkbox.
    *
    * Note: This attempts to toggle the checkbox as a user would, by clicking it. Therefore if you
    * are using `MAT_CHECKBOX_CLICK_ACTION` to change the behavior on click, calling this method
@@ -116,8 +114,7 @@ export class MatCheckboxHarness extends ComponentHarness {
 
   /**
    * Puts the checkbox in a checked state by toggling it if it is currently unchecked, or doing
-   * nothing if it is already checked. Returns a void promise that indicates when the action is
-   * complete.
+   * nothing if it is already checked.
    *
    * Note: This attempts to check the checkbox as a user would, by clicking it. Therefore if you
    * are using `MAT_CHECKBOX_CLICK_ACTION` to change the behavior on click, calling this method
@@ -131,8 +128,7 @@ export class MatCheckboxHarness extends ComponentHarness {
 
   /**
    * Puts the checkbox in an unchecked state by toggling it if it is currently checked, or doing
-   * nothing if it is already unchecked. Returns a void promise that indicates when the action is
-   * complete.
+   * nothing if it is already unchecked.
    *
    * Note: This attempts to uncheck the checkbox as a user would, by clicking it. Therefore if you
    * are using `MAT_CHECKBOX_CLICK_ACTION` to change the behavior on click, calling this method

src/material/dialog/testing/dialog-harness-filters.ts

@@ -8,4 +8,5 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
+/** A set of criteria that can be used to filter a list of `MatDialogHarness` instances. */
 export interface DialogHarnessFilters extends BaseHarnessFilters {}

src/material/dialog/testing/dialog-harness.ts

@@ -10,17 +10,17 @@ import {ComponentHarness, HarnessPredicate, TestKey} from '@angular/cdk/testing'
 import {DialogRole} from '@angular/material/dialog';
 import {DialogHarnessFilters} from './dialog-harness-filters';
 
-/** Harness for interacting with a standard MatDialog in tests. */
+/** Harness for interacting with a standard `MatDialog` in tests. */
 export class MatDialogHarness extends ComponentHarness {
   // Developers can provide a custom component or template for the
   // dialog. The canonical dialog parent is the "MatDialogContainer".
+  /** The selector for the host element of a `MatDialog` instance. */
   static hostSelector = '.mat-dialog-container';
 
   /**
-   * Gets a `HarnessPredicate` that can be used to search for a dialog with
-   * specific attributes.
-   * @param options Options for narrowing the search:
-   *   - `id` finds a dialog with specific id.
+   * Gets a `HarnessPredicate` that can be used to search for a `MatDialogHarness` that meets
+   * certain criteria.
+   * @param options Options for filtering which dialog instances are considered a match.
    * @return a `HarnessPredicate` configured with the given options.
    */
   static with(options: DialogHarnessFilters = {}): HarnessPredicate<MatDialogHarness> {
@@ -56,8 +56,9 @@ export class MatDialogHarness extends ComponentHarness {
   }
 
   /**
-   * Closes the dialog by pressing escape. Note that this method cannot
-   * be used if "disableClose" has been set to true for the dialog.
+   * Closes the dialog by pressing escape.
+   *
+   * Note: this method does nothing if `disableClose` has been set to `true` for the dialog.
    */
   async close(): Promise<void> {
     await (await this.host()).sendKeys(TestKey.ESCAPE);