style: Add explanations to tslint:disable comments (#4448)

All `tslint:disable:object-literal-sort-keys` comments now include a description that explains why the linter rule needs to be disabled. For the most part, it's to ensure consistent ordering of methods between adapter interfaces and their implementations in the foundation and component.

This PR also reorders a few properties in `MDCCheckbox` and `MDCRadio` for consistency.

Refs #4225

Author: acdvorak

packages/mdc-checkbox/component.ts

@@ -33,24 +33,47 @@ import {MDCCheckboxFoundation} from './foundation';
  */
 type PropertyDescriptorGetter = (() => any) | undefined; // tslint:disable-line:no-any
 
-const {NATIVE_CONTROL_SELECTOR} = MDCCheckboxFoundation.strings;
-
 const CB_PROTO_PROPS = ['checked', 'indeterminate'];
 
 export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements MDCRippleCapableSurface {
   static attachTo(root: Element) {
     return new MDCCheckbox(root);
   }
 
-  /**
-   * Returns the state of the native control element, or null if the native control element is not present.
-   */
-  get nativeCb_(): HTMLInputElement {
-    const cbEl = this.root_.querySelector<HTMLInputElement>(NATIVE_CONTROL_SELECTOR);
-    if (!cbEl) {
-      throw new Error(`Checkbox requires a ${NATIVE_CONTROL_SELECTOR} element`);
-    }
-    return cbEl;
+  get ripple(): MDCRipple {
+    return this.ripple_;
+  }
+
+  get checked(): boolean {
+    return this.nativeControl_.checked;
+  }
+
+  set checked(checked: boolean) {
+    this.nativeControl_.checked = checked;
+  }
+
+  get indeterminate(): boolean {
+    return this.nativeControl_.indeterminate;
+  }
+
+  set indeterminate(indeterminate: boolean) {
+    this.nativeControl_.indeterminate = indeterminate;
+  }
+
+  get disabled(): boolean {
+    return this.nativeControl_.disabled;
+  }
+
+  set disabled(disabled: boolean) {
+    this.foundation_.setDisabled(disabled);
+  }
+
+  get value(): string {
+    return this.nativeControl_.value;
+  }
+
+  set value(value: string) {
+    this.nativeControl_.value = value;
   }
 
   // Public visibility for this property is required by MDCRippleCapableSurface.
@@ -63,14 +86,14 @@ export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements
   initialSyncWithDOM() {
     this.handleChange_ = () => this.foundation_.handleChange();
     this.handleAnimationEnd_ = () => this.foundation_.handleAnimationEnd();
-    this.nativeCb_.addEventListener('change', this.handleChange_);
+    this.nativeControl_.addEventListener('change', this.handleChange_);
     this.listen(getCorrectEventName(window, 'animationend'), this.handleAnimationEnd_);
     this.installPropertyChangeHooks_();
   }
 
   destroy() {
     this.ripple_.destroy();
-    this.nativeCb_.removeEventListener('change', this.handleChange_);
+    this.nativeControl_.removeEventListener('change', this.handleChange_);
     this.unlisten(getCorrectEventName(window, 'animationend'), this.handleAnimationEnd_);
     this.uninstallPropertyChangeHooks_();
     super.destroy();
@@ -82,14 +105,14 @@ export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements
     const adapter: MDCCheckboxAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       forceLayout: () => (this.root_ as HTMLElement).offsetWidth,
-      hasNativeControl: () => !!this.nativeCb_,
+      hasNativeControl: () => !!this.nativeControl_,
       isAttachedToDOM: () => Boolean(this.root_.parentNode),
       isChecked: () => this.checked,
       isIndeterminate: () => this.indeterminate,
       removeClass: (className) => this.root_.classList.remove(className),
-      removeNativeControlAttr: (attr) => this.nativeCb_.removeAttribute(attr),
-      setNativeControlAttr: (attr, value) => this.nativeCb_.setAttribute(attr, value),
-      setNativeControlDisabled: (disabled) => this.nativeCb_.disabled = disabled,
+      removeNativeControlAttr: (attr) => this.nativeControl_.removeAttribute(attr),
+      setNativeControlAttr: (attr, value) => this.nativeControl_.setAttribute(attr, value),
+      setNativeControlDisabled: (disabled) => this.nativeControl_.disabled = disabled,
     };
     return new MDCCheckboxFoundation(adapter);
   }
@@ -99,16 +122,16 @@ export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
     const adapter: MDCRippleAdapter = {
       ...MDCRipple.createAdapter(this),
-      deregisterInteractionHandler: (evtType, handler) => this.nativeCb_.removeEventListener(evtType, handler),
-      isSurfaceActive: () => ponyfill.matches(this.nativeCb_, ':active'),
+      deregisterInteractionHandler: (evtType, handler) => this.nativeControl_.removeEventListener(evtType, handler),
+      isSurfaceActive: () => ponyfill.matches(this.nativeControl_, ':active'),
       isUnbounded: () => true,
-      registerInteractionHandler: (evtType, handler) => this.nativeCb_.addEventListener(evtType, handler),
+      registerInteractionHandler: (evtType, handler) => this.nativeControl_.addEventListener(evtType, handler),
     };
     return new MDCRipple(this.root_, new MDCRippleFoundation(adapter));
   }
 
   private installPropertyChangeHooks_() {
-    const nativeCb = this.nativeCb_;
+    const nativeCb = this.nativeControl_;
     const cbProto = Object.getPrototypeOf(nativeCb);
 
     CB_PROTO_PROPS.forEach((controlState) => {
@@ -136,7 +159,7 @@ export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements
   }
 
   private uninstallPropertyChangeHooks_() {
-    const nativeCb = this.nativeCb_;
+    const nativeCb = this.nativeControl_;
     const cbProto = Object.getPrototypeOf(nativeCb);
 
     CB_PROTO_PROPS.forEach((controlState) => {
@@ -148,40 +171,13 @@ export class MDCCheckbox extends MDCComponent<MDCCheckboxFoundation> implements
     });
   }
 
-  get ripple(): MDCRipple {
-    return this.ripple_;
-  }
-
-  get checked(): boolean {
-    return this.nativeCb_.checked;
-  }
-
-  set checked(checked: boolean) {
-    this.nativeCb_.checked = checked;
-  }
-
-  get indeterminate(): boolean {
-    return this.nativeCb_.indeterminate;
-  }
-
-  set indeterminate(indeterminate: boolean) {
-    this.nativeCb_.indeterminate = indeterminate;
-  }
-
-  get disabled(): boolean {
-    return this.nativeCb_.disabled;
-  }
-
-  set disabled(disabled: boolean) {
-    this.foundation_.setDisabled(disabled);
-  }
-
-  get value(): string {
-    return this.nativeCb_.value;
-  }
-
-  set value(value: string) {
-    this.nativeCb_.value = value;
+  private get nativeControl_(): HTMLInputElement {
+    const {NATIVE_CONTROL_SELECTOR} = MDCCheckboxFoundation.strings;
+    const el = this.root_.querySelector<HTMLInputElement>(NATIVE_CONTROL_SELECTOR);
+    if (!el) {
+      throw new Error(`Checkbox component requires a ${NATIVE_CONTROL_SELECTOR} element`);
+    }
+    return el;
   }
 }
 

packages/mdc-drawer/component.ts

@@ -118,7 +118,7 @@ export class MDCDrawer extends MDCComponent<MDCDismissibleDrawerFoundation> {
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCDrawerAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       removeClass: (className) => this.root_.classList.remove(className),

packages/mdc-drawer/dismissible/foundation.ts

@@ -35,7 +35,7 @@ export class MDCDismissibleDrawerFoundation extends MDCFoundation<MDCDrawerAdapt
   }
 
   static get defaultAdapter(): MDCDrawerAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClass: () => undefined,
       removeClass: () => undefined,

packages/mdc-floating-label/component.ts

@@ -55,7 +55,7 @@ export class MDCFloatingLabel extends MDCComponent<MDCFloatingLabelFoundation> {
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCFloatingLabelAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       removeClass: (className) => this.root_.classList.remove(className),

packages/mdc-floating-label/foundation.ts

@@ -35,7 +35,7 @@ export class MDCFloatingLabelFoundation extends MDCFoundation<MDCFloatingLabelAd
    * See {@link MDCFloatingLabelAdapter} for typing information on parameters and return types.
    */
   static get defaultAdapter(): MDCFloatingLabelAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClass: () => undefined,
       removeClass: () => undefined,

packages/mdc-line-ripple/component.ts

@@ -57,7 +57,7 @@ export class MDCLineRipple extends MDCComponent<MDCLineRippleFoundation> {
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCLineRippleAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       removeClass: (className) => this.root_.classList.remove(className),

packages/mdc-line-ripple/foundation.ts

@@ -35,7 +35,7 @@ export class MDCLineRippleFoundation extends MDCFoundation<MDCLineRippleAdapter>
    * See {@link MDCLineRippleAdapter} for typing information on parameters and return types.
    */
   static get defaultAdapter(): MDCLineRippleAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClass: () => undefined,
       removeClass: () => undefined,

packages/mdc-menu-surface/component.ts

@@ -149,7 +149,7 @@ export class MDCMenuSurface extends MDCComponent<MDCMenuSurfaceFoundation> {
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCMenuSurfaceAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       removeClass: (className) => this.root_.classList.remove(className),

packages/mdc-menu-surface/foundation.ts

@@ -56,7 +56,7 @@ export class MDCMenuSurfaceFoundation extends MDCFoundation<MDCMenuSurfaceAdapte
    * @see {@link MDCMenuSurfaceAdapter} for typing information on parameters and return types.
    */
   static get defaultAdapter(): MDCMenuSurfaceAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClass: () => undefined,
       removeClass: () => undefined,
@@ -292,9 +292,8 @@ export class MDCMenuSurfaceFoundation extends MDCFoundation<MDCMenuSurfaceAdapte
     const viewportSize = this.adapter_.getWindowDimensions();
     const windowScroll = this.adapter_.getWindowScroll();
 
-    // tslint:disable:object-literal-sort-keys
-
     if (!anchorRect) {
+      // tslint:disable:object-literal-sort-keys Positional properties are more readable when they're grouped together
       anchorRect = {
         top: this.position_.y,
         right: this.position_.x,
@@ -303,23 +302,24 @@ export class MDCMenuSurfaceFoundation extends MDCFoundation<MDCMenuSurfaceAdapte
         width: 0,
         height: 0,
       };
+      // tslint:enable:object-literal-sort-keys
     }
 
     return {
       anchorSize: anchorRect,
       bodySize,
       surfaceSize: this.dimensions_,
       viewportDistance: {
+        // tslint:disable:object-literal-sort-keys Positional properties are more readable when they're grouped together
         top: anchorRect.top,
         right: viewportSize.width - anchorRect.right,
         bottom: viewportSize.height - anchorRect.bottom,
         left: anchorRect.left,
+        // tslint:enable:object-literal-sort-keys
       },
       viewportSize,
       windowScroll,
     };
-
-    // tslint:enable:object-literal-sort-keys
   }
 
   /**

packages/mdc-menu/component.ts

@@ -176,7 +176,7 @@ export class MDCMenu extends MDCComponent<MDCMenuFoundation> {
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCMenuAdapter = {
       addClassToElementAtIndex: (index, className) => {
         const list = this.items;

packages/mdc-menu/foundation.ts

@@ -42,7 +42,7 @@ export class MDCMenuFoundation extends MDCFoundation<MDCMenuAdapter> {
    * @see {@link MDCMenuAdapter} for typing information on parameters and return types.
    */
   static get defaultAdapter(): MDCMenuAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClassToElementAtIndex: () => undefined,
       removeClassFromElementAtIndex: () => undefined,

packages/mdc-notched-outline/component.ts

@@ -69,7 +69,7 @@ export class MDCNotchedOutline extends MDCComponent<MDCNotchedOutlineFoundation>
   getDefaultFoundation() {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCNotchedOutlineAdapter = {
       addClass: (className) => this.root_.classList.add(className),
       removeClass: (className) => this.root_.classList.remove(className),

packages/mdc-notched-outline/foundation.ts

@@ -42,7 +42,7 @@ export class MDCNotchedOutlineFoundation extends MDCFoundation<MDCNotchedOutline
    * See {@link MDCNotchedOutlineAdapter} for typing information on parameters and return types.
    */
   static get defaultAdapter(): MDCNotchedOutlineAdapter {
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     return {
       addClass: () => undefined,
       removeClass: () => undefined,

packages/mdc-radio/component.ts

@@ -31,11 +31,6 @@ export class MDCRadio extends MDCComponent<MDCRadioFoundation> implements MDCRip
     return new MDCRadio(root);
   }
 
-  // Public visibility for this property is required by MDCRippleCapableSurface.
-  root_!: Element; // assigned in MDCComponent constructor
-
-  private readonly ripple_: MDCRipple = this.createRipple_();
-
   get checked(): boolean {
     return this.nativeControl_.checked;
   }
@@ -64,6 +59,11 @@ export class MDCRadio extends MDCComponent<MDCRadioFoundation> implements MDCRip
     return this.ripple_;
   }
 
+  // Public visibility for this property is required by MDCRippleCapableSurface.
+  root_!: Element; // assigned in MDCComponent constructor
+
+  private readonly ripple_: MDCRipple = this.createRipple_();
+
   destroy() {
     this.ripple_.destroy();
     super.destroy();
@@ -83,7 +83,7 @@ export class MDCRadio extends MDCComponent<MDCRadioFoundation> implements MDCRip
   private createRipple_(): MDCRipple {
     // DO NOT INLINE this variable. For backward compatibility, foundations take a Partial<MDCFooAdapter>.
     // To ensure we don't accidentally omit any methods, we need a separate, strongly typed adapter variable.
-    // tslint:disable:object-literal-sort-keys
+    // tslint:disable:object-literal-sort-keys Methods should be in the same order as the adapter interface.
     const adapter: MDCRippleAdapter = {
       ...MDCRipple.createAdapter(this),
       registerInteractionHandler: (evtType, handler) => this.nativeControl_.addEventListener(evtType, handler),
@@ -97,9 +97,6 @@ export class MDCRadio extends MDCComponent<MDCRadioFoundation> implements MDCRip
     return new MDCRipple(this.root_, new MDCRippleFoundation(adapter));
   }
 
-  /**
-   * Returns the state of the native control element, or null if the native control element is not present.
-   */
   private get nativeControl_(): HTMLInputElement {
     const {NATIVE_CONTROL_SELECTOR} = MDCRadioFoundation.strings;
     const el = this.root_.querySelector<HTMLInputElement>(NATIVE_CONTROL_SELECTOR);