more docs

Author: kseamon

src/material/datepicker/calendar-body.ts

@@ -455,6 +455,10 @@ export class MatCalendarBody<D = any> implements OnChanges, OnDestroy, AfterView
     }
   };
 
+  /**
+   * Triggered on mousedown or touchstart on a date cell.
+   * Respsonsible for starting a drag sequence.
+   */
   private _mousedownHandler = (event: Event) => {
     this._didDragSinceMouseDown = false;
     // Begin a drag if a cell within the current range was targeted.
@@ -471,6 +475,7 @@ export class MatCalendarBody<D = any> implements OnChanges, OnDestroy, AfterView
     });
   };
 
+  /** Triggered on mouseup anywhere. Respsonsible for ending a drag sequence. */
   private _mouseupHandler = (event: Event) => {
     const cellElement = getCellElement(event.target as HTMLElement);
     if (!cellElement) {
@@ -493,6 +498,7 @@ export class MatCalendarBody<D = any> implements OnChanges, OnDestroy, AfterView
     });
   };
 
+  /** Triggered on touchend anywhere. Respsonsible for ending a drag sequence. */
   private _touchendHandler = (event: TouchEvent) => {
     const target = getActualTouchTarget(event);
 
@@ -529,6 +535,10 @@ function isTableCell(node: Node | undefined | null): node is HTMLTableCellElemen
   return node?.nodeName === 'TD';
 }
 
+/**
+ * Gets the date table cell element that is or contains the specified element.
+ * Or returns null if element is not part of a date cell.
+ */
 function getCellElement(element: HTMLElement): HTMLElement | null {
   let cell: HTMLElement | undefined;
   if (isTableCell(element)) {
@@ -569,6 +579,10 @@ function isInRange(
   );
 }
 
+/**
+ * Extracts the element that actually corresponds to a touch event's location
+ * (rather than the element that initiated the sequence of touch events).
+ */
 function getActualTouchTarget(event: TouchEvent): Element | null {
   const touchLocation = event.changedTouches[0];
   return document.elementFromPoint(touchLocation.clientX, touchLocation.clientY);

src/material/datepicker/calendar.ts

@@ -504,10 +504,15 @@ export class MatCalendar<D> implements AfterContentInit, AfterViewChecked, OnDes
     this.currentView = view;
   }
 
+  /** Called when the user starts dragging to change a date range. */
   _dragStarted(event: MatCalendarUserEvent<D>) {
     this._activeDrag = event;
   }
 
+  /**
+   * Called when a drag completes. It may end in cancelation or in the selection
+   * of a new range.
+   */
   _dragEnded(event: MatCalendarUserEvent<DateRange<D> | null>) {
     if (!this._activeDrag) return;
 

src/material/datepicker/month-view.ts

@@ -161,8 +161,13 @@ export class MatMonthView<D> implements AfterContentInit, OnChanges, OnDestroy {
   @Output() readonly _userSelection: EventEmitter<MatCalendarUserEvent<D | null>> =
     new EventEmitter<MatCalendarUserEvent<D | null>>();
 
+  /** Emits when the user initiates a date range drag via mouse or touch. */
   @Output() readonly dragStarted = new EventEmitter<MatCalendarUserEvent<D>>();
 
+  /**
+   * Emits when the user completes or cancels a date range drag.
+   * Emits null when the drag was canceled or the newly selected date range if completed.
+   */
   @Output() readonly dragEnded = new EventEmitter<MatCalendarUserEvent<DateRange<D> | null>>();
 
   /** Emits when any date is activated. */
@@ -461,6 +466,10 @@ export class MatMonthView<D> implements AfterContentInit, OnChanges, OnDestroy {
     }
   }
 
+  /**
+   * Called when the user has ended a drag. If the drag/drop was successful,
+   * computes and emits the new range selection.
+   */
   protected _dragEnded(event: MatCalendarUserEvent<D | null>) {
     if (!this._activeDrag) return;
 
@@ -606,6 +615,7 @@ export class MatMonthView<D> implements AfterContentInit, OnChanges, OnDestroy {
     return !this.dateFilter || this.dateFilter(date);
   }
 
+  /** Clears out preview state. */
   private _clearPreview() {
     this._previewStart = this._previewEnd = null;
   }