address comments

Author: mmalerba

src/lib/core/datetime/date-adapter.ts

@@ -118,7 +118,7 @@ export abstract class DateAdapter<D> {
   abstract today(): D;
 
   /**
-   * Parses a date from a value.
+   * Parses a date from a user-inputted value.
    * @param value The value to parse.
    * @param parseFormat The expected format of the value being parsed
    *     (type is implementation-dependent).
@@ -127,7 +127,7 @@ export abstract class DateAdapter<D> {
   abstract parse(value: any, parseFormat: any): D | null;
 
   /**
-   * Formats a date as a string.
+   * Formats a date as a string according to the given format.
    * @param date The value to format.
    * @param displayFormat The format to use to display the date as a string.
    * @returns The formatted date string.
@@ -165,6 +165,8 @@ export abstract class DateAdapter<D> {
 
   /**
    * Gets the RFC 3339 compatible string (https://tools.ietf.org/html/rfc3339) for the given date.
+   * This method is used to generate date strings that are compatible with native HTML attributes
+   * such as the `min` or `max` attribute of an `<input>`.
    * @param date The date to get the ISO date string for.
    * @returns The ISO date string date string.
    */
@@ -185,20 +187,23 @@ export abstract class DateAdapter<D> {
   abstract isValid(date: D): boolean;
 
   /**
-   * Attempts to coerce a value to a valid date object. This is different from parsing in that it
-   * should only coerce non-ambiguous, locale-independent values (e.g. a ISO 8601 string).
-   * The default implementation does not allow any coercion, it simply checks that the given value
-   * is already a valid date object or null.
-   * @param value The value to be coerced to a date object.
-   * @returns The coerced date object, either a valid date, null if the value can be coerced to a
-   *     null date (e.g. the empty string).
-   * @throws If the given value cannot be coerced to a valid date or null.
+   * Attempts to deserialize a value to a valid date object. This is different from parsing in that
+   * deserialize should only accept non-ambiguous, locale-independent values (e.g. a ISO 8601
+   * string). The default implementation does not allow any deserialization, it simply checks that
+   * the given value is already a valid date object or null. The `<mat-datepicker>` will call this
+   * method on all of it's `@Input()` properties that accept dates. It is therefore possible to
+   * support passing your wire format directly to these properties by overriding this method to
+   * also deserialize your wire format.
+   * @param value The value to be deserialized into a date object.
+   * @returns The deserialized date object, either a valid date, null if the value can be
+   *     deserialized into a null date (e.g. the empty string).
+   * @throws If the given value cannot be deserialized into a valid date or null.
    */
-  coerceToDate(value: any): D | null {
+  deserialize(value: any): D | null {
     if (value == null || this.isDateInstance(value) && this.isValid(value)) {
       return value;
     }
-    throw Error(`Could not coerce "${value}" to a valid date object.`);
+    throw Error(`Could not deserialize "${value}" into a valid date object.`);
   }
 
   /**

src/lib/core/datetime/native-date-adapter.spec.ts

@@ -334,18 +334,18 @@ describe('NativeDateAdapter', () => {
   });
 
   it('should create dates from valid ISO strings', () => {
-    expect(adapter.coerceToDate('1985-04-12T23:20:50.52Z')).not.toBeNull();
-    expect(adapter.coerceToDate('1996-12-19T16:39:57-08:00')).not.toBeNull();
-    expect(adapter.coerceToDate('1937-01-01T12:00:27.87+00:20')).not.toBeNull();
-    expect(adapter.coerceToDate('2017-01-01')).not.toBeNull();
-    expect(adapter.coerceToDate('2017-01-01T00:00:00')).not.toBeNull();
-    expect(() => adapter.coerceToDate('1990-13-31T23:59:00Z')).toThrow();
-    expect(() => adapter.coerceToDate('1/1/2017')).toThrow();
-    expect(() => adapter.coerceToDate('2017-01-01T')).toThrow();
-    expect(adapter.coerceToDate('')).toBeNull();
-    expect(adapter.coerceToDate(null)).toBeNull();
-    expect(adapter.coerceToDate(new Date())).not.toBeNull();
-    expect(() => adapter.coerceToDate(new Date(NaN))).toThrow();
+    expect(adapter.deserialize('1985-04-12T23:20:50.52Z')).not.toBeNull();
+    expect(adapter.deserialize('1996-12-19T16:39:57-08:00')).not.toBeNull();
+    expect(adapter.deserialize('1937-01-01T12:00:27.87+00:20')).not.toBeNull();
+    expect(adapter.deserialize('2017-01-01')).not.toBeNull();
+    expect(adapter.deserialize('2017-01-01T00:00:00')).not.toBeNull();
+    expect(() => adapter.deserialize('1990-13-31T23:59:00Z')).toThrow();
+    expect(() => adapter.deserialize('1/1/2017')).toThrow();
+    expect(() => adapter.deserialize('2017-01-01T')).toThrow();
+    expect(adapter.deserialize('')).toBeNull();
+    expect(adapter.deserialize(null)).toBeNull();
+    expect(adapter.deserialize(new Date())).not.toBeNull();
+    expect(() => adapter.deserialize(new Date(NaN))).toThrow();
   });
 });
 

src/lib/core/datetime/native-date-adapter.ts

@@ -221,11 +221,11 @@ export class NativeDateAdapter extends DateAdapter<Date> {
   }
 
   /**
-   * Returns the given value if given a valid Date or null. Coerces valid ISO 8601 strings
-   * (https://www.ietf.org/rfc/rfc3339.txt) to valid Dates and empty string to null. Throws on all
-   * other values.
+   * Returns the given value if given a valid Date or null. Deserializes valid ISO 8601 strings
+   * (https://www.ietf.org/rfc/rfc3339.txt) into valid Dates and empty string into null. Throws on
+   * all other values.
    */
-  coerceToDate(value: any): Date | null {
+  deserialize(value: any): Date | null {
     if (typeof value === 'string') {
       if (!value) {
         return null;
@@ -239,7 +239,7 @@ export class NativeDateAdapter extends DateAdapter<Date> {
         }
       }
     }
-    return super.coerceToDate(value);
+    return super.deserialize(value);
   }
 
   isDateInstance(obj: any) {

src/lib/datepicker/calendar.ts

@@ -66,7 +66,7 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
   /** A date representing the period (month or year) to start the calendar in. */
   @Input()
   get startAt(): D | null { return this._startAt; }
-  set startAt(value: D | null) { this._startAt = this._dateAdapter.coerceToDate(value); }
+  set startAt(value: D | null) { this._startAt = this._dateAdapter.deserialize(value); }
   private _startAt: D | null;
 
   /** Whether the calendar should be started in month or year view. */
@@ -75,19 +75,19 @@ export class MatCalendar<D> implements AfterContentInit, OnDestroy, OnChanges {
   /** The currently selected date. */
   @Input()
   get selected(): D | null { return this._selected; }
-  set selected(value: D | null) { this._selected = this._dateAdapter.coerceToDate(value); }
+  set selected(value: D | null) { this._selected = this._dateAdapter.deserialize(value); }
   private _selected: D | null;
 
   /** The minimum selectable date. */
   @Input()
   get minDate(): D | null { return this._minDate; }
-  set minDate(value: D | null) { this._minDate = this._dateAdapter.coerceToDate(value); }
+  set minDate(value: D | null) { this._minDate = this._dateAdapter.deserialize(value); }
   private _minDate: D | null;
 
   /** The maximum selectable date. */
   @Input()
   get maxDate(): D | null { return this._maxDate; }
-  set maxDate(value: D | null) { this._maxDate = this._dateAdapter.coerceToDate(value); }
+  set maxDate(value: D | null) { this._maxDate = this._dateAdapter.deserialize(value); }
   private _maxDate: D | null;
 
   /** A function used to filter which dates are selectable. */

src/lib/datepicker/coerce-date-property.spec.ts

@@ -112,7 +112,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
     return this._value;
   }
   set value(value: D | null) {
-    value = this._dateAdapter.coerceToDate(value);
+    value = this._dateAdapter.deserialize(value);
     this._lastValueValid = !value || this._dateAdapter.isValid(value);
     value = this._getValidDateOrNull(value);
 
@@ -130,7 +130,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
   @Input()
   get min(): D | null { return this._min; }
   set min(value: D | null) {
-    this._min = this._dateAdapter.coerceToDate(value);
+    this._min = this._dateAdapter.deserialize(value);
     this._validatorOnChange();
   }
   private _min: D | null;
@@ -139,7 +139,7 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
   @Input()
   get max(): D | null { return this._max; }
   set max(value: D | null) {
-    this._max = this._dateAdapter.coerceToDate(value);
+    this._max = this._dateAdapter.deserialize(value);
     this._validatorOnChange();
   }
   private _max: D | null;
@@ -187,23 +187,23 @@ export class MatDatepickerInput<D> implements AfterContentInit, ControlValueAcce
 
   /** The form control validator for the min date. */
   private _minValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = this._dateAdapter.coerceToDate(control.value);
+    const controlValue = this._dateAdapter.deserialize(control.value);
     return (!this.min || !controlValue ||
         this._dateAdapter.compareDate(this.min, controlValue) <= 0) ?
         null : {'matDatepickerMin': {'min': this.min, 'actual': controlValue}};
   }
 
   /** The form control validator for the max date. */
   private _maxValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = this._dateAdapter.coerceToDate(control.value);
+    const controlValue = this._dateAdapter.deserialize(control.value);
     return (!this.max || !controlValue ||
         this._dateAdapter.compareDate(this.max, controlValue) >= 0) ?
         null : {'matDatepickerMax': {'max': this.max, 'actual': controlValue}};
   }
 
   /** The form control validator for the date filter. */
   private _filterValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
-    const controlValue = this._dateAdapter.coerceToDate(control.value);
+    const controlValue = this._dateAdapter.deserialize(control.value);
     return !this._dateFilter || !controlValue || this._dateFilter(controlValue) ?
         null : {'matDatepickerFilter': true};
   }

src/lib/datepicker/coerce-date-property.ts

@@ -276,7 +276,7 @@ describe('MatDatepicker', () => {
         testComponent.date = '1/1/2017' as any;
 
         expect(() => fixture.detectChanges())
-            .toThrowError('Could not coerce "1/1/2017" to a valid date object.');
+            .toThrowError('Could not deserialize "1/1/2017" into a valid date object.');
 
         testComponent.date = null;
       });

src/lib/datepicker/datepicker-input.ts

@@ -132,7 +132,7 @@ export class MatDatepicker<D> implements OnDestroy {
     // selected value is.
     return this._startAt || (this._datepickerInput ? this._datepickerInput.value : null);
   }
-  set startAt(date: D | null) { this._startAt = this._dateAdapter.coerceToDate(date); }
+  set startAt(date: D | null) { this._startAt = this._dateAdapter.deserialize(date); }
   private _startAt: D | null;
 
   /** The view that the calendar should start in. */

src/lib/datepicker/datepicker.spec.ts

@@ -46,7 +46,7 @@ export class MatMonthView<D> implements AfterContentInit {
   get activeDate(): D { return this._activeDate; }
   set activeDate(value: D) {
     let oldActiveDate = this._activeDate;
-    this._activeDate = this._dateAdapter.coerceToDate(value) || this._dateAdapter.today();
+    this._activeDate = this._dateAdapter.deserialize(value) || this._dateAdapter.today();
     if (!this._hasSameMonthAndYear(oldActiveDate, this._activeDate)) {
       this._init();
     }
@@ -57,7 +57,7 @@ export class MatMonthView<D> implements AfterContentInit {
   @Input()
   get selected(): D | null { return this._selected; }
   set selected(value: D | null) {
-    this._selected = this._dateAdapter.coerceToDate(value);
+    this._selected = this._dateAdapter.deserialize(value);
     this._selectedDate = this._getDateInCurrentMonth(this._selected);
   }
   private _selected: D | null;