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;
 }