docs: fill out jsdoc for button, checkbox, and radio (#2252)

* docs: fill out jsdoc for button, checkbox, and radio

* Fix bad rename, re-add isAriaDisabled

src/lib/button-toggle/button-toggle.ts

@@ -34,6 +34,7 @@ export type ToggleType = 'checkbox' | 'radio';
 /**
  * Provider Expression that allows md-button-toggle-group to register as a ControlValueAccessor.
  * This allows it to support [(ngModel)].
+ * @docs-private
  */
 export const MD_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR: any = {
   provide: NG_VALUE_ACCESSOR,
@@ -43,7 +44,7 @@ export const MD_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR: any = {
 
 var _uniqueIdCounter = 0;
 
-/** A simple change event emitted by either MdButtonToggle or MdButtonToggleGroup. */
+/** Change event object emitted by MdButtonToggle. */
 export class MdButtonToggleChange {
   source: MdButtonToggle;
   value: any;

src/lib/button/button.html

@@ -1,8 +1,8 @@
 <span class="md-button-wrapper"><ng-content></ng-content></span>
 <div md-ripple *ngIf="!_isRippleDisabled()" class="md-button-ripple"
-    [class.md-button-ripple-round]="isRoundButton()"
-    [md-ripple-trigger]="getHostElement()"
-    [md-ripple-color]="isRoundButton() ? 'rgba(255, 255, 255, 0.2)' : ''"
+    [class.md-button-ripple-round]="_isRoundButton()"
+    [md-ripple-trigger]="_getHostElement()"
+    [md-ripple-color]="_isRoundButton() ? 'rgba(255, 255, 255, 0.2)' : ''"
     md-ripple-background-color="rgba(0, 0, 0, 0)"></div>
 <!-- the touchstart handler prevents the overlay from capturing the initial tap on touch devices -->
 <div class="md-button-focus-overlay" (touchstart)="$event.preventDefault()"></div>

src/lib/button/button.ts

@@ -47,24 +47,22 @@ export class MdButton {
   private _disableRipple: boolean = false;
   private _disabled: boolean = null;
 
+  /** Whether the ripple effect for this button is disabled. */
   @Input()
   get disableRipple() { return this._disableRipple; }
   set disableRipple(v) { this._disableRipple = coerceBooleanProperty(v); }
 
+  /** Whether the button is disabled. */
   @Input()
   get disabled() { return this._disabled; }
   set disabled(value: boolean) { this._disabled = coerceBooleanProperty(value) ? true : null; }
 
   constructor(private _elementRef: ElementRef, private _renderer: Renderer) { }
 
+  /** The color of the button. Can be `primary`, `accent`, or `warn`. */
   @Input()
-  get color(): string {
-    return this._color;
-  }
-
-  set color(value: string) {
-    this._updateColor(value);
-  }
+  get color(): string { return this._color; }
+  set color(value: string) { this._updateColor(value); }
 
   _setMousedown() {
     // We only *show* the focus style when focus has come to the button via the keyboard.
@@ -95,16 +93,16 @@ export class MdButton {
     this._isKeyboardFocused = false;
   }
 
-  /** TODO(hansl): e2e test this function. */
-  focus() {
+  /** Focuses the button. */
+  focus(): void {
     this._renderer.invokeElementMethod(this._elementRef.nativeElement, 'focus');
   }
 
-  getHostElement() {
+  _getHostElement() {
     return this._elementRef.nativeElement;
   }
 
-  isRoundButton() {
+  _isRoundButton() {
     const el = this._elementRef.nativeElement;
     return el.hasAttribute('md-icon-button') ||
         el.hasAttribute('md-fab') ||
@@ -122,6 +120,7 @@ export class MdButton {
   inputs: ['color', 'disabled', 'disableRipple'],
   host: {
     '[attr.disabled]': 'disabled',
+    '[attr.aria-disabled]': '_isAriaDisabled',
     '[class.md-button-focus]': '_isKeyboardFocused',
     '(mousedown)': '_setMousedown()',
     '(focus)': '_setKeyboardFocus()',
@@ -137,14 +136,13 @@ export class MdAnchor extends MdButton {
     super(elementRef, renderer);
   }
 
+  /** @docs-private */
   @HostBinding('tabIndex')
   get tabIndex(): number {
     return this.disabled ? -1 : 0;
   }
 
-  /** Gets the aria-disabled value for the component, which must be a string for Dart. */
-  @HostBinding('attr.aria-disabled')
-  get isAriaDisabled(): string {
+  get _isAriaDisabled(): string {
     return this.disabled ? 'true' : 'false';
   }
 

src/lib/checkbox/checkbox.html

@@ -16,7 +16,7 @@
            (change)="_onInteractionEvent($event)"
            (click)="_onInputClick($event)">
     <div md-ripple *ngIf="!_isRippleDisabled()" class="md-checkbox-ripple"
-         [md-ripple-trigger]="getHostElement()"
+         [md-ripple-trigger]="_getHostElement()"
          [md-ripple-centered]="true"
          [md-ripple-speed-factor]="0.3"
          md-ripple-background-color="rgba(0, 0, 0, 0)"></div>

src/lib/checkbox/checkbox.ts

@@ -20,14 +20,13 @@ import {MdRippleModule, DefaultStyleCompatibilityModeModule} from '../core';
 import {ViewportRuler} from '../core/overlay/position/viewport-ruler';
 
 
-/**
- * Monotonically increasing integer used to auto-generate unique ids for checkbox components.
- */
+/** Monotonically increasing integer used to auto-generate unique ids for checkbox components. */
 let nextId = 0;
 
 /**
- * Provider Expression that allows md-checkbox to register as a ControlValueAccessor. This allows it
- * to support [(ngModel)].
+ * Provider Expression that allows md-checkbox to register as a ControlValueAccessor.
+ * This allows it to support [(ngModel)].
+ * @docs-private
  */
 export const MD_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = {
   provide: NG_VALUE_ACCESSOR,
@@ -37,6 +36,7 @@ export const MD_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = {
 
 /**
  * Represents the different states that require custom transitions between them.
+ * @docs-private
  */
 export enum TransitionCheckState {
   /** The initial state of the component before any user interaction. */
@@ -49,7 +49,7 @@ export enum TransitionCheckState {
   Indeterminate
 }
 
-// A simple change event emitted by the MdCheckbox component.
+/** Change event object emitted by MdCheckbox. */
 export class MdCheckboxChange {
   source: MdCheckbox;
   checked: boolean;
@@ -73,7 +73,7 @@ export class MdCheckboxChange {
     '[class.md-checkbox-checked]': 'checked',
     '[class.md-checkbox-disabled]': 'disabled',
     '[class.md-checkbox-align-end]': 'align == "end"',
-    '[class.md-checkbox-focused]': 'hasFocus',
+    '[class.md-checkbox-focused]': '_hasFocus',
   },
   providers: [MD_CHECKBOX_CONTROL_VALUE_ACCESSOR],
   encapsulation: ViewEncapsulation.None,
@@ -97,18 +97,19 @@ export class MdCheckbox implements ControlValueAccessor {
   /** Whether the ripple effect on click should be disabled. */
   private _disableRipple: boolean;
 
+  /** Whether the ripple effect for this checkbox is disabled. */
   @Input()
   get disableRipple(): boolean { return this._disableRipple; }
   set disableRipple(value) { this._disableRipple = coerceBooleanProperty(value); }
 
-  /** ID to be applied to the `input` element */
+  /** ID of the native input element inside `<md-checkbox>` */
   get inputId(): string {
     return `input-${this.id}`;
   }
 
   private _required: boolean;
 
-  /** Whether the checkbox is required or not. */
+  /** Whether the checkbox is required. */
   @Input()
   get required(): boolean { return this._required; }
   set required(value) { this._required = coerceBooleanProperty(value); }
@@ -118,18 +119,12 @@ export class MdCheckbox implements ControlValueAccessor {
 
   private _disabled: boolean = false;
 
-  /**
-   * Whether the checkbox is disabled. When the checkbox is disabled it cannot be interacted with.
-   * The correct ARIA attributes are applied to denote this to assistive technology.
-   */
+  /** Whether the checkbox is disabled. */
   @Input()
   get disabled(): boolean { return this._disabled; }
   set disabled(value) { this._disabled = coerceBooleanProperty(value); }
 
-  /**
-   * The tabindex attribute for the checkbox. Note that when the checkbox is disabled, the attribute
-   * on the host element will be removed. It will be placed back when the checkbox is re-enabled.
-   */
+  /** @docs-private */
   @Input() tabindex: number = 0;
 
   /** Name value will be applied to the input element if present */
@@ -141,7 +136,10 @@ export class MdCheckbox implements ControlValueAccessor {
   /** The native `<input type=checkbox> element */
   @ViewChild('input') _inputElement: ElementRef;
 
-  /** Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor. */
+  /**
+   * Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor.
+   * @docs-private
+   */
   onTouched: () => any = () => {};
 
   private _currentAnimationClass: string = '';
@@ -156,7 +154,7 @@ export class MdCheckbox implements ControlValueAccessor {
 
   private _controlValueAccessorChangeFn: (value: any) => void = (value) => {};
 
-  hasFocus: boolean = false;
+  _hasFocus: boolean = false;
 
   constructor(private _renderer: Renderer,
               private _elementRef: ElementRef,
@@ -205,15 +203,10 @@ export class MdCheckbox implements ControlValueAccessor {
     }
   }
 
-  /** Sets the color of the checkbox */
+  /** The color of the button. Can be `primary`, `accent`, or `warn`. */
   @Input()
-  get color(): string {
-    return this._color;
-  }
-
-  set color(value: string) {
-    this._updateColor(value);
-  }
+  get color(): string { return this._color; }
+  set color(value: string) { this._updateColor(value); }
 
   _updateColor(newColor: string) {
     this._setElementColor(this._color, false);
@@ -283,19 +276,17 @@ export class MdCheckbox implements ControlValueAccessor {
 
   /** Informs the component when the input has focus so that we can style accordingly */
   _onInputFocus() {
-    this.hasFocus = true;
+    this._hasFocus = true;
   }
 
   /** Informs the component when we lose focus in order to style accordingly */
   _onInputBlur() {
-    this.hasFocus = false;
+    this._hasFocus = false;
     this.onTouched();
   }
 
-  /**
-   * Toggles the `checked` value between true and false
-   */
-  toggle() {
+  /** Toggles the `checked` state of the checkbox. */
+  toggle(): void {
     this.checked = !this.checked;
   }
 
@@ -320,7 +311,8 @@ export class MdCheckbox implements ControlValueAccessor {
     }
   }
 
-  focus() {
+  /** Focuses the checkbox. */
+  focus(): void {
     this._renderer.invokeElementMethod(this._inputElement.nativeElement, 'focus');
     this._onInputFocus();
   }
@@ -366,7 +358,7 @@ export class MdCheckbox implements ControlValueAccessor {
     return `md-checkbox-anim-${animSuffix}`;
   }
 
-  getHostElement() {
+  _getHostElement() {
     return this._elementRef.nativeElement;
   }
 }

src/lib/radio/radio.html

@@ -6,7 +6,7 @@
     <div class="md-radio-outer-circle"></div>
     <div class="md-radio-inner-circle"></div>
     <div md-ripple *ngIf="!_isRippleDisabled()" class="md-radio-ripple"
-         [md-ripple-trigger]="getHostElement()"
+         [md-ripple-trigger]="_getHostElement()"
          [md-ripple-centered]="true"
          [md-ripple-speed-factor]="0.3"
          md-ripple-background-color="rgba(0, 0, 0, 0)"></div>
@@ -25,7 +25,7 @@
           (click)="_onInputClick($event)">
 
   <!-- The label content for radio control. -->
-  <div class="md-radio-label-content" [class.md-radio-align-end]="align == 'end'">
+  <div class="md-radio-label-content" [class.md-radio-align-end]="align == 'after'">
     <ng-content></ng-content>
   </div>
 </label>

src/lib/radio/radio.ts

@@ -32,6 +32,7 @@ import {ViewportRuler} from '../core/overlay/position/viewport-ruler';
 /**
  * Provider Expression that allows md-radio-group to register as a ControlValueAccessor. This
  * allows it to support [(ngModel)] and ngControl.
+ * @docs-private
  */
 export const MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR: any = {
   provide: NG_VALUE_ACCESSOR,
@@ -39,22 +40,17 @@ export const MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR: any = {
   multi: true
 };
 
-// TODO(mtlin):
-// Ink ripple is currently placeholder.
-// Determine motion spec for button transitions.
-// Design review.
-// RTL
-// Support forms API.
-// Use ChangeDetectionStrategy.OnPush
-
 var _uniqueIdCounter = 0;
 
-/** A simple change event emitted by either MdRadioButton or MdRadioGroup. */
+/** Change event object emitted by MdRadio and MdRadioGroup. */
 export class MdRadioChange {
   source: MdRadioButton;
   value: any;
 }
 
+/**
+ * A group of radio buttons. May contain one or more `<md-radio-button>` elements.
+ */
 @Directive({
   selector: 'md-radio-group, mat-radio-group',
   providers: [MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR],
@@ -86,10 +82,17 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor {
   /** The method to be called in order to update ngModel */
   _controlValueAccessorChangeFn: (value: any) => void = (value) => {};
 
-  /** onTouch function registered via registerOnTouch (ControlValueAccessor). */
+  /**
+   * onTouch function registered via registerOnTouch (ControlValueAccessor).
+   * @docs-private
+   */
   onTouched: () => any = () => {};
 
-  /** Event emitted when the group value changes. */
+  /**
+   * Event emitted when the group value changes.
+   * Change events are only emitted when the value changes due to user interaction with
+   * a radio button (the same behavior as `<input type-"radio">`).
+   */
   @Output()
   change: EventEmitter<MdRadioChange> = new EventEmitter<MdRadioChange>();
 
@@ -97,6 +100,7 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor {
   @ContentChildren(forwardRef(() => MdRadioButton))
   _radios: QueryList<MdRadioButton> = null;
 
+  /** Name of the radio button group. All radio buttons inside this group will use this name. */
   @Input()
   get name(): string {
     return this._name;
@@ -107,7 +111,8 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor {
     this._updateRadioButtonNames();
   }
 
-  @Input() align: 'start' | 'end';
+  /** Alignment of the radio-buttons relative to their labels. Can be 'before' or 'after'. */
+  @Input() align: 'before' | 'after';
 
   @Input()
   get disabled(): boolean {
@@ -228,7 +233,9 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor {
   }
 }
 
-
+/**
+ * A radio-button. May be inside of
+ */
 @Component({
   moduleId: module.id,
   selector: 'md-radio-button, mat-radio-button',
@@ -271,15 +278,20 @@ export class MdRadioButton implements OnInit {
   /** The parent radio group. May or may not be present. */
   radioGroup: MdRadioGroup;
 
+  /** Whether the ripple effect for this radio button is disabled. */
   @Input()
   get disableRipple(): boolean { return this._disableRipple; }
   set disableRipple(value) { this._disableRipple = coerceBooleanProperty(value); }
 
-  /** Event emitted when the group value changes. */
+  /**
+   * Event emitted when the checked state of this radio button changes.
+   * Change events are only emitted when the value changes due to user interaction with
+   * the radio button (the same behavior as `<input type-"radio">`).
+   */
   @Output()
   change: EventEmitter<MdRadioChange> = new EventEmitter<MdRadioChange>();
 
-  /** The native `<input type=radio> element */
+  /** The native `<input type=radio>` element */
   @ViewChild('input') _inputElement: ElementRef;
 
   constructor(@Optional() radioGroup: MdRadioGroup,
@@ -298,10 +310,12 @@ export class MdRadioButton implements OnInit {
     });
   }
 
+  /** ID of the native input element inside `<md-radio-button>` */
   get inputId(): string {
     return `${this.id}-input`;
   }
 
+  /** Whether this radio button is checked. */
   @HostBinding('class.md-radio-checked')
   @Input()
   get checked(): boolean {
@@ -327,7 +341,7 @@ export class MdRadioButton implements OnInit {
     }
   }
 
-  /** MdRadioGroup reads this to assign its own value. */
+  /** The value of this radio button. */
   @Input()
   get value(): any {
     return this._value;
@@ -349,17 +363,19 @@ export class MdRadioButton implements OnInit {
     }
   }
 
-  private _align: 'start' | 'end';
+  private _align: 'before' | 'after';
 
+  /** Alignment of the radio-button relative to their labels. Can be 'before' or 'after'. */
   @Input()
-  get align(): 'start' | 'end' {
-    return this._align || (this.radioGroup != null && this.radioGroup.align) || 'start';
+  get align(): 'before' | 'after' {
+    return this._align || (this.radioGroup != null && this.radioGroup.align) || 'before';
   }
 
-  set align(value: 'start' | 'end') {
+  set align(value: 'before' | 'after') {
     this._align = value;
   }
 
+  /** Whether the radio button is disabled. */
   @HostBinding('class.md-radio-disabled')
   @Input()
   get disabled(): boolean {
@@ -401,7 +417,8 @@ export class MdRadioButton implements OnInit {
     this._isFocused = true;
   }
 
-  focus() {
+  /** Focuses the radio button. */
+  focus(): void {
     this._renderer.invokeElementMethod(this._inputElement.nativeElement, 'focus');
     this._onInputFocus();
   }
@@ -448,7 +465,7 @@ export class MdRadioButton implements OnInit {
     }
   }
 
-  getHostElement() {
+  _getHostElement() {
     return this._elementRef.nativeElement;
   }
 }