docs: add jsdoc to public interfaces (#8568)

Author: mmalerba

src/cdk/a11y/activedescendant-key-manager.ts

@@ -14,7 +14,10 @@ import {ListKeyManager, ListKeyManagerOption} from './list-key-manager';
  * currently disabled.
  */
 export interface Highlightable extends ListKeyManagerOption {
+  /** Applies the styles for an active item to this item. */
   setActiveStyles(): void;
+
+  /** Applies the styles for an inactive item to this item. */
   setInactiveStyles(): void;
 }
 

src/cdk/a11y/aria-describer.ts

@@ -12,10 +12,13 @@ import {addAriaReferencedId, getAriaReferenceIds, removeAriaReferencedId} from '
 
 /**
  * Interface used to register message elements and keep a count of how many registrations have
- * the same message and the reference to the message element used for the aria-describedby.
+ * the same message and the reference to the message element used for the `aria-describedby`.
  */
 export interface RegisteredMessage {
+  /** The element containing the message. */
   messageElement: Element;
+
+  /** The number of elements that reference this message element via `aria-describedby`. */
   referenceCount: number;
 }
 

src/cdk/a11y/focus-key-manager.ts

@@ -14,6 +14,7 @@ import {ListKeyManager, ListKeyManagerOption} from './list-key-manager';
  * and be able to supply it's label.
  */
 export interface FocusableOption extends ListKeyManagerOption {
+  /** Focuses the `FocusableOption`. */
   focus(): void;
 }
 

src/cdk/a11y/list-key-manager.ts

@@ -17,7 +17,10 @@ import {tap} from 'rxjs/operators/tap';
 
 /** This interface is for items that can be passed to a ListKeyManager. */
 export interface ListKeyManagerOption {
+  /** Whether the option is disabled. */
   disabled?: boolean;
+
+  /** Gets the label for this option. */
   getLabel?(): string;
 }
 

src/cdk/collections/collection-viewer.ts

@@ -13,5 +13,9 @@ import {Observable} from 'rxjs/Observable';
  * information regarding the view and any changes made.
  */
 export interface CollectionViewer {
+  /**
+   * A stream that emits whenever the `CollectionViewer` starts looking at a new portion of the
+   * data. The `start` index is inclusive, while the `end` is exclusive.
+   */
   viewChange: Observable<{start: number, end: number}>;
 }

src/cdk/layout/breakpoints-observer.ts

@@ -18,6 +18,7 @@ import {fromEventPattern} from 'rxjs/observable/fromEventPattern';
 
 /** The current state of a layout breakpoint. */
 export interface BreakpointState {
+  /** Whether the breakpoint is currently matching. */
   matches: boolean;
 }
 

src/cdk/overlay/scroll/scroll-strategy.ts

@@ -9,12 +9,16 @@
 import {OverlayRef} from '../overlay-ref';
 
 /**
- * Describes a strategy that will be used by an overlay
- * to handle scroll events while it is open.
+ * Describes a strategy that will be used by an overlay to handle scroll events while it is open.
  */
 export interface ScrollStrategy {
+  /** Enable this scroll strategy (called when the attached overlay is attached to a portal). */
   enable: () => void;
+
+  /** Disable this scroll strategy (called when the attached overlay is detached from a portal). */
   disable: () => void;
+
+  /** Attaches this `ScrollStrategy` to an overlay. */
   attach: (overlayRef: OverlayRef) => void;
 }
 

src/cdk/portal/portal.ts

@@ -146,16 +146,18 @@ export class TemplatePortal<C> extends Portal<C> {
 }
 
 
-/**
- * A `PortalOutlet` is an space that can contain a single `Portal`.
- */
+/** A `PortalOutlet` is an space that can contain a single `Portal`. */
 export interface PortalOutlet {
+  /** Attaches a portal to this outlet. */
   attach(portal: Portal<any>): any;
 
+  /** Detaches the currently attached portal from this outlet. */
   detach(): any;
 
+  /** Performs cleanup before the outlet is destroyed. */
   dispose(): void;
 
+  /** Whether there is currently a portal attached to this outlet. */
   hasAttached(): boolean;
 }
 

src/lib/chips/chip-input.ts

@@ -12,8 +12,12 @@ import {Directive, ElementRef, EventEmitter, Input, Output} from '@angular/core'
 import {MatChipList} from './chip-list';
 
 
+/** Represents an input event on a `matChipInput`. */
 export interface MatChipInputEvent {
+  /** The native `<input>` element that the event is being fired for. */
   input: HTMLInputElement;
+
+  /** The value of the input. */
   value: string;
 }
 

src/lib/chips/chip.ts

@@ -22,7 +22,9 @@ import {CanColor, CanDisable, mixinColor, mixinDisabled} from '@angular/material
 import {Subject} from 'rxjs/Subject';
 
 
+/** Represents an event fired on an individual `mat-chip`. */
 export interface MatChipEvent {
+  /** The chip the event was fired on. */
   chip: MatChip;
 }
 

src/lib/core/placeholder/placeholder-options.ts

@@ -15,6 +15,11 @@ export const MAT_PLACEHOLDER_GLOBAL_OPTIONS =
 /** Type for the available floatPlaceholder values. */
 export type FloatPlaceholderType = 'always' | 'never' | 'auto';
 
+/** Configurable options for floating placeholders. */
 export interface PlaceholderOptions {
+  /**
+   * Whether the placeholder should float `always`, `never`, or `auto` (only when necessary).
+   * Default behavior is assumed to be `auto`.
+   */
   float?: FloatPlaceholderType;
 }

src/lib/core/ripple/ripple.ts

@@ -22,6 +22,7 @@ import {Platform} from '@angular/cdk/platform';
 import {RippleConfig, RippleRenderer} from './ripple-renderer';
 import {RippleRef} from './ripple-ref';
 
+/** Configurable options for `matRipple`. */
 export interface RippleGlobalOptions {
   /**
    * Whether ripples should be disabled. Ripples can be still launched manually by using

src/lib/dialog/dialog-config.ts

@@ -14,9 +14,16 @@ export type DialogRole = 'dialog' | 'alertdialog';
 
 /** Possible overrides for a dialog's position. */
 export interface DialogPosition {
+  /** Override for the dialog's top position. */
   top?: string;
+
+  /** Override for the dialog's bottom position. */
   bottom?: string;
+
+  /** Override for the dialog's left position. */
   left?: string;
+
+  /** Override for the dialog's right position. */
   right?: string;
 }
 

src/lib/menu/menu-directive.ts

@@ -44,8 +44,13 @@ import {coerceBooleanProperty} from '@angular/cdk/coercion';
 
 /** Default `mat-menu` options that can be overridden. */
 export interface MatMenuDefaultOptions {
+  /** The x-axis position of the menu. */
   xPosition: MenuPositionX;
+
+  /** The y-axis position of the menu. */
   yPosition: MenuPositionY;
+
+  /** Whether the menu should overlap the menu trigger. */
   overlapTrigger: boolean;
 }
 

src/lib/menu/menu-panel.ts

@@ -10,6 +10,10 @@ import {EventEmitter, TemplateRef} from '@angular/core';
 import {MenuPositionX, MenuPositionY} from './menu-positions';
 import {Direction} from '@angular/cdk/bidi';
 
+/**
+ * Interface for a custom menu panel that can be used with `matMenuTriggerFor`.
+ * @docs-private
+ */
 export interface MatMenuPanel {
   xPosition: MenuPositionX;
   yPosition: MenuPositionY;

src/lib/sort/sort.ts

@@ -15,14 +15,24 @@ import {
   getSortHeaderMissingIdError
 } from './sort-errors';
 
+/** Interface for a directive that holds sorting state consumed by `MatSortHeader`. */
 export interface MatSortable {
+  /** The id of the column being sorted. */
   id: string;
+
+  /** Starting sort direction. */
   start: 'asc' | 'desc';
+
+  /** Whether to disable clearing the sorting state. */
   disableClear: boolean;
 }
 
+/** The current sort state. */
 export interface Sort {
+  /** The id of the column being sorted. */
   active: string;
+
+  /** The sort direction. */
   direction: SortDirection;
 }