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

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> {
@@ -39,7 +39,7 @@ export class MatAutocompleteHarness extends ComponentHarness {
             (harness, value) => HarnessPredicate.stringMatches(harness.getValue(), value));
   }
 
-  /** Gets the value of the autocomplete input. */
+  /** Gets a promise for the value of the autocomplete input. */
   async getValue(): Promise<string> {
     return (await this.host()).getProperty('value');
   }
@@ -65,12 +65,12 @@ export class MatAutocompleteHarness extends ComponentHarness {
     return (await this.host()).sendKeys(value);
   }
 
-  /** Gets the options inside the autocomplete panel. */
+  /** Gets a promise for the options inside the autocomplete panel. */
   async getOptions(filters: OptionHarnessFilters = {}): Promise<MatAutocompleteOptionHarness[]> {
     return this._documentRootLocator.locatorForAll(MatAutocompleteOptionHarness.with(filters))();
   }
 
-  /** Gets the groups of options inside the panel. */
+  /** Gets a promise for the option groups inside the 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. */
+  /** Gets a boolean promise indicating 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,25 +11,44 @@ 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,
             (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text));
   }
 
-  /** Clicks the option. */
+  /**
+   * Clicks the option.
+   * @return A promise that resolves when the action is complete.
+   */
   async select(): Promise<void> {
     return (await this.host()).click();
   }
@@ -43,8 +62,16 @@ 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,

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> {

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> {

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,54 +10,55 @@ 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> {
     return new HarnessPredicate(MatDialogHarness, options);
   }
 
-  /** Gets the id of the dialog. */
+  /** Gets a promise for the id of the dialog. */
   async getId(): Promise<string|null> {
     const id = await (await this.host()).getAttribute('id');
     // In case no id has been specified, the "id" property always returns
     // an empty string. To make this method more explicit, we return null.
     return id !== '' ? id : null;
   }
 
-  /** Gets the role of the dialog. */
+  /** Gets a promise for the role of the dialog. */
   async getRole(): Promise<DialogRole|null> {
     return (await this.host()).getAttribute('role') as Promise<DialogRole|null>;
   }
 
-  /** Gets the value of the dialog's "aria-label" attribute. */
+  /** Gets a promise for the value of the dialog's "aria-label" attribute. */
   async getAriaLabel(): Promise<string|null> {
     return (await this.host()).getAttribute('aria-label');
   }
 
-  /** Gets the value of the dialog's "aria-labelledby" attribute. */
+  /** Gets a promise for the value of the dialog's "aria-labelledby" attribute. */
   async getAriaLabelledby(): Promise<string|null> {
     return (await this.host()).getAttribute('aria-labelledby');
   }
 
-  /** Gets the value of the dialog's "aria-describedby" attribute. */
+  /** Gets a promise for the value of the dialog's "aria-describedby" attribute. */
   async getAriaDescribedby(): Promise<string|null> {
     return (await this.host()).getAttribute('aria-describedby');
   }
 
   /**
-   * 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 cannot be used if `disableClose` has been set to `true` for the dialog.
    */
   async close(): Promise<void> {
     await (await this.host()).sendKeys(TestKey.ESCAPE);

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

@@ -8,11 +8,16 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
+/** A set of criteria that can be used to filter a list of `MatMenuHarness` instances. */
 export interface MenuHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose trigger text matches the given value. */
   triggerText?: string | RegExp;
 }
 
+/** A set of criteria that can be used to filter a list of `MatMenuItemHarness` instances. */
 export interface MenuItemHarnessFilters extends BaseHarnessFilters {
+  /** Only find instances whose text matches the given value. */
   text?: string | RegExp;
+  /** Only find instances that have a sub-menu. */
   hasSubmenu?: boolean;
 }