Add a lot of JSDoc

Author: kseamon

src/cdk-experimental/column-resize/column-resize-directives/column-resize-flex.ts

@@ -15,7 +15,7 @@ import {HeaderRowEventDispatcher} from '../event-dispatcher';
 import {HOST_BINDINGS, FLEX_PROVIDERS} from './constants';
 
 /**
- * Explicitly enables column resizing for a flex cdk-table.
+ * Explicitly enables column resizing for a flexbox-based cdk-table.
  * Individual columns must be annotated specifically.
  */
 @Directive({

src/cdk-experimental/column-resize/column-resize-module.ts

@@ -17,12 +17,20 @@ import {
   CdkDefaultEnabledColumnResizeFlex
 } from './column-resize-directives/default-enabled-column-resize-flex';
 
+/**
+ * One of two NgModules for use with CdkColumnResize.
+ * When using this module, columns are resizable by default.
+ */
 @NgModule({
   declarations: [CdkDefaultEnabledColumnResize, CdkDefaultEnabledColumnResizeFlex],
   exports: [CdkDefaultEnabledColumnResize, CdkDefaultEnabledColumnResizeFlex],
 })
 export class CdkColumnResizeDefaultEnabledModule {}
 
+/**
+ * One of two NgModules for use with CdkColumnResize.
+ * When using this module, columns are not resizable by default.
+ */
 @NgModule({
   declarations: [CdkColumnResize, CdkColumnResizeFlex],
   exports: [CdkColumnResize, CdkColumnResizeFlex],

src/cdk-experimental/column-resize/column-resize-notifier.ts

@@ -9,29 +9,47 @@
 import {Injectable} from '@angular/core';
 import {Observable, Subject} from 'rxjs';
 
+/** Indicates the width of a column. */
 export interface ColumnSize {
+  /** The ID/name of the column, as defined in CdkColumnDef. */
   readonly columnId: string;
+
+  /** The width in pixels of the column. */
   readonly size: number;
 }
 
+/** Interface describing column size changes. */
 export interface ColumnSizeAction extends ColumnSize {
+  /**
+   * Whether the resize action should be applied instantaneously. False for events triggered during
+   * a UI-triggered resize (such as with the mouse) until the mouse button is released. True
+   * for all programatically triggered resizes.
+   */
   readonly completeImmediately?: boolean;
 }
 
+/** Conduit for resize-releated events within the table. */
 @Injectable()
 export class ColumnResizeNotifierSource {
+  /** Emits when an in-progress resize is canceled. */
   readonly resizeCanceled = new Subject<ColumnSizeAction>();
+
+  /** Emits when a resize is applied. */
   readonly resizeCompleted = new Subject<ColumnSize>();
+
+  /** Triggers a resize action. */
   readonly triggerResize = new Subject<ColumnSizeAction>();
 }
 
 /** Service for triggering column resizes imperatively or being notified of them. */
 @Injectable()
 export class ColumnResizeNotifier {
+  /** Emits whenever a column is resized. */
   readonly resizeCompleted: Observable<ColumnSize> = this._source.resizeCompleted.asObservable();
 
   constructor(private readonly _source: ColumnResizeNotifierSource) {}
 
+  /** Instantly resizes the specified column. */
   resize(columnId: string, size: number): void {
     this._source.triggerResize.next({columnId, size, completeImmediately: true});
   }

src/cdk-experimental/column-resize/column-resize.ts

@@ -38,8 +38,10 @@ export abstract class ColumnResize implements AfterViewInit, OnDestroy {
   protected abstract readonly ngZone: NgZone;
   protected abstract readonly notifier: ColumnResizeNotifierSource;
 
+  /** Unique ID for this table instance. */
   protected readonly selectorId = `${++nextId}`;
 
+  /** The id attribute of the table, if specified. */
   id?: string;
 
   ngAfterViewInit() {
@@ -55,6 +57,7 @@ export abstract class ColumnResize implements AfterViewInit, OnDestroy {
     this.destroyed.complete();
   }
 
+  /** Gets the unique CSS class name for this table instance. */
   getUniqueCssClass() {
     return `cdk-column-resize-${this.selectorId}`;
   }

src/cdk-experimental/column-resize/column-size-store.ts

@@ -13,6 +13,9 @@ import {Injectable} from '@angular/core';
  */
 @Injectable()
 export abstract class ColumnSizeStore {
+  /** Returns the persisted size of the specified column in the specified table. */
   abstract getSize(tableId: string, columnId: string): number;
+
+  /** Persists the size of the specified column in the specified table. */
   abstract setSize(tableId: string, columnId: string): void;
 }

src/cdk-experimental/column-resize/constants.ts

@@ -6,6 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+// TODO: Figure out how to remove `mat-` classes from the CDK part of the
+// column resize implementation.
+
 export const HEADER_CELL_SELECTOR = '.cdk-header-cell, .mat-header-cell';
 
 export const HEADER_ROW_SELECTOR = '.cdk-header-row, .mat-header-row';

src/cdk-experimental/column-resize/event-dispatcher.ts

@@ -14,20 +14,34 @@ import {_closest} from '@angular/cdk-experimental/popover-edit';
 
 import {HEADER_ROW_SELECTOR} from './constants';
 
+/** Coordinates events between the column resize directives. */
 @Injectable()
 export class HeaderRowEventDispatcher {
+  /**
+   * Emits the currently hovered header cell or null when no header cells are hovered.
+   * Exposed publicly for events to feed in, but subscribers should use headerCellHoveredDistinct,
+   * defined below.
+   */
   readonly headerCellHovered = new Subject<Element|null>();
 
-  // element refers to header row
+  /**
+   * Emits the header cell for which a user-triggered resize is active or null
+   * when no resize is in progress.
+   */
   readonly overlayHandleActiveForCell = new Subject<Element|null>();
 
   constructor(private readonly _ngZone: NgZone) {}
 
+  /** Distinct and shared version of headerCellHovered. */
   readonly headerCellHoveredDistinct = this.headerCellHovered.pipe(
       distinctUntilChanged(),
       share(),
   );
 
+  /**
+   * Emits the header that is currently hovered or hosting an active resize event (with active
+   * taking precedence).
+   */
   readonly headerRowHoveredOrActiveDistinct = combineLatest(
       this.headerCellHoveredDistinct.pipe(
           map(cell => _closest(cell, HEADER_ROW_SELECTOR)),
@@ -57,6 +71,10 @@ export class HeaderRowEventDispatcher {
   private _lastSeenRow: Element|null = null;
   private _lastSeenRowHover: Observable<boolean>|null = null;
 
+  /**
+   * Emits whether the specified row should show its overlay controls.
+   * Emission occurs within the NgZone.
+   */
   resizeOverlayVisibleForHeaderRow(row: Element): Observable<boolean> {
     if (row !== this._lastSeenRow) {
       this._lastSeenRow = row;

src/cdk-experimental/column-resize/resizable.ts

@@ -58,6 +58,7 @@ export abstract class Resizable<HandleComponent extends ResizeOverlayHandle>
   protected abstract readonly resizeStrategy: ResizeStrategy;
   protected abstract readonly viewContainerRef: ViewContainerRef;
 
+  /** The minimum width to allow the column to be sized to. */
   get minWidthPx(): number {
     return this.minWidthPxInternal;
   }
@@ -69,6 +70,7 @@ export abstract class Resizable<HandleComponent extends ResizeOverlayHandle>
     }
   }
 
+  /** The maximum width to allow the column to be sized to. */
   get maxWidthPx(): number {
     return this.maxWidthPxInternal;
   }

src/cdk-experimental/column-resize/resize-ref.ts

@@ -9,6 +9,7 @@
 import {ElementRef} from '@angular/core';
 import {OverlayRef} from '@angular/cdk/overlay';
 
+/** Tracks state of resize events in progress. */
 export class ResizeRef {
   constructor(
       readonly origin: ElementRef,

src/material-experimental/column-resize/column-resize-directives/column-resize-flex.ts

@@ -18,7 +18,7 @@ import {
 import {AbstractMatColumnResize, FLEX_HOST_BINDINGS, FLEX_PROVIDERS} from './common';
 
 /**
- * Explicitly enables column resizing for a flex mat-table.
+ * Explicitly enables column resizing for a flexbox-based mat-table.
  * Individual columns must be annotated specifically.
  */
 @Directive({

src/material-experimental/column-resize/column-resize-directives/default-enabled-column-resize-flex.ts

@@ -18,7 +18,7 @@ import {
 import {AbstractMatColumnResize, FLEX_HOST_BINDINGS, FLEX_PROVIDERS} from './common';
 
 /**
- * Implicitly enables column resizing for a flex mat-table.
+ * Implicitly enables column resizing for a flexbox-based mat-table.
  * Individual columns will be resizable unless opted out.
  */
 @Directive({