docs: add jsdoc annotations everywhere (#2321)

* docs: add jsdoc annotations everywhere

Adds JSDoc annotations to all of the public properties and methods that were missing them. Also cleans up some random issues that were noticed while going through everything.

* Remove the types from the @return annotations and add return type where missing.

* Remove @docs-private from the lifecycle hooks.

* Typo.

* Better line wrapping.

Author: crisbeto

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

@@ -26,7 +26,7 @@ import {
   DefaultStyleCompatibilityModeModule,
 } from '../core';
 
-
+/** Acceptable types for a button toggle. */
 export type ToggleType = 'checkbox' | 'radio';
 
 
@@ -102,6 +102,7 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     this._isInitialized = true;
   }
 
+  /** `name` attribute for the underlying `input` element. */
   @Input()
   get name(): string {
     return this._name;
@@ -112,6 +113,7 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     this._updateButtonToggleNames();
   }
 
+  /** Whether the toggle group is disabled. */
   @Input()
   get disabled(): boolean {
     return this._disabled;
@@ -121,6 +123,7 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     this._disabled = coerceBooleanProperty(value);
   }
 
+  /** Whether the toggle group is vertical. */
   @Input()
   get vertical(): boolean {
     return this._vertical;
@@ -130,6 +133,7 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     this._vertical = coerceBooleanProperty(value);
   }
 
+  /** Value of the toggle group. */
   @Input()
   get value(): any {
     return this._value;
@@ -149,6 +153,7 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     }
   }
 
+  /** Whether the toggle group is selected. */
   @Input()
   get selected() {
     return this._selected;
@@ -199,17 +204,28 @@ export class MdButtonToggleGroup implements AfterViewInit, ControlValueAccessor
     this._change.emit(event);
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Sets the model value. Implemented as part of ControlValueAccessor.
+   * @param value Value to be set to the model.
+   */
   writeValue(value: any) {
     this.value = value;
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Registers a callback that will be triggered when the value has changed.
+   * Implemented as part of ControlValueAccessor.
+   * @param fn On change callback function.
+   */
   registerOnChange(fn: (value: any) => void) {
     this._controlValueAccessorChangeFn = fn;
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Registers a callback that will be triggered when the control has been touched.
+   * Implemented as part of ControlValueAccessor.
+   * @param fn On touch callback function.
+   */
   registerOnTouched(fn: any) {
     this.onTouched = fn;
   }
@@ -230,6 +246,7 @@ export class MdButtonToggleGroupMultiple {
   /** Whether the button toggle group should be vertical. */
   private _vertical: boolean = false;
 
+  /** Whether the toggle group is disabled. */
   @Input()
   get disabled(): boolean {
     return this._disabled;
@@ -239,6 +256,7 @@ export class MdButtonToggleGroupMultiple {
     this._disabled = (value != null && value !== false) ? true : null;
   }
 
+  /** Whether the toggle group is vertical. */
   @Input()
   get vertical(): boolean {
     return this._vertical;
@@ -250,6 +268,7 @@ export class MdButtonToggleGroupMultiple {
 
 }
 
+/** Single button inside of a toggle group. */
 @Component({
   moduleId: module.id,
   selector: 'md-button-toggle',
@@ -332,10 +351,12 @@ export class MdButtonToggle implements OnInit {
     }
   }
 
+  /** Unique ID for the underlying `input` element. */
   get inputId(): string {
     return `${this.id}-input`;
   }
 
+  /** Whether the button is checked. */
   @HostBinding('class.md-button-toggle-checked')
   @Input()
   get checked(): boolean {
@@ -380,6 +401,7 @@ export class MdButtonToggle implements OnInit {
     this._change.emit(event);
   }
 
+  /** Whether the button is disabled. */
   @HostBinding('class.md-button-toggle-disabled')
   @Input()
   get disabled(): boolean {
@@ -425,6 +447,7 @@ export class MdButtonToggle implements OnInit {
     event.stopPropagation();
   }
 
+  /** Focuses the button. */
   focus() {
     this._renderer.invokeElementMethod(this._inputElement.nativeElement, 'focus');
   }

src/lib/button/button.ts

@@ -17,7 +17,9 @@ import {ViewportRuler} from '../core/overlay/position/viewport-ruler';
 // TODO(jelbourn): Make the `isMouseDown` stuff done with one global listener.
 // TODO(kara): Convert attribute selectors to classes when attr maps become available
 
-
+/**
+ * Material design button.
+ */
 @Component({
   moduleId: module.id,
   selector: 'button[md-button], button[md-raised-button], button[md-icon-button], ' +
@@ -114,6 +116,9 @@ export class MdButton {
   }
 }
 
+/**
+ * Raised Material design button.
+ */
 @Component({
   moduleId: module.id,
   selector: 'a[md-button], a[md-raised-button], a[md-icon-button], a[md-fab], a[md-mini-fab]',

src/lib/card/card.ts

@@ -50,25 +50,17 @@ export class MdCardActions {}
 export class MdCardFooter {}
 
 
-/*
-
-<md-card> is a basic content container component that adds the styles of a material design card.
-
-While you can use this component alone,
-it also provides a number of preset styles for common card sections, including:
- - md-card-title
- - md-card-subtitle
- - md-card-content
- - md-card-actions
- - md-card-footer
-
- You can see some examples of cards here:
- http://embed.plnkr.co/s5O4YcyvbLhIApSrIhtj/
-
- TODO(kara): update link to demo site when it exists
-
-*/
-
+/**
+ * A basic content container component that adds the styles of a Material design card.
+ *
+ * While this component can be used alone, it also provides a number
+ * of preset styles for common card sections, including:
+ * - md-card-title
+ * - md-card-subtitle
+ * - md-card-content
+ * - md-card-actions
+ * - md-card-footer
+ */
 @Component({
   moduleId: module.id,
   selector: 'md-card, mat-card',
@@ -80,20 +72,10 @@ it also provides a number of preset styles for common card sections, including:
 export class MdCard {}
 
 
-/*  The following components don't have any behavior.
- They simply use content projection to wrap user content
- for flex layout purposes in <md-card> (and thus allow a cleaner, boilerplate-free API).
-
-
-<md-card-header> is a component intended to be used within the <md-card> component.
-It adds styles for a preset header section (i.e. a title, subtitle, and avatar layout).
-
-You can see an example of a card with a header here:
-http://embed.plnkr.co/tvJl19z3gZTQd6WmwkIa/
-
-TODO(kara): update link to demo site when it exists
-*/
-
+/**
+ * Component intended to be used within the `<md-card>` component. It adds styles for a
+ * preset header section (i.e. a title, subtitle, and avatar layout).
+ */
 @Component({
   moduleId: module.id,
   selector: 'md-card-header, mat-card-header',
@@ -103,17 +85,11 @@ TODO(kara): update link to demo site when it exists
 })
 export class MdCardHeader {}
 
-/*
-
-<md-card-title-group> is a component intended to be used within the <md-card> component.
-It adds styles for a preset layout that groups an image with a title section.
-
-You can see an example of a card with a title-group section here:
-http://embed.plnkr.co/EDfgCF9eKcXjini1WODm/
-
-TODO(kara): update link to demo site when it exists
-*/
 
+/**
+ * Component intended to be used within the <md-card> component. It adds styles for a preset
+ * layout that groups an image with a title section.
+ */
 @Component({
   moduleId: module.id,
   selector: 'md-card-title-group, mat-card-title-group',

src/lib/checkbox/checkbox.ts

@@ -57,7 +57,7 @@ export class MdCheckboxChange {
 
 /**
  * A material design checkbox component. Supports all of the functionality of an HTML5 checkbox,
- * and exposes a similar API. An MdCheckbox can be either checked, unchecked, indeterminate, or
+ * and exposes a similar API. A MdCheckbox can be either checked, unchecked, indeterminate, or
  * disabled. Note that all additional accessibility attributes are taken care of by the component,
  * so there is no need to provide them yourself. However, if you want to omit a label and still
  * have the checkbox be accessible, you may supply an [aria-label] input.
@@ -148,7 +148,7 @@ export class MdCheckbox implements ControlValueAccessor {
   /** Event emitted when the checkbox's `checked` value changes. */
   @Output() change: EventEmitter<MdCheckboxChange> = new EventEmitter<MdCheckboxChange>();
 
-  /** The native `<input type=checkbox> element */
+  /** The native `<input type="checkbox"> element */
   @ViewChild('input') _inputElement: ElementRef;
 
   /**
@@ -239,22 +239,36 @@ export class MdCheckbox implements ControlValueAccessor {
     return this.disableRipple || this.disabled;
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Sets the model value. Implemented as part of ControlValueAccessor.
+   * @param value Value to be set to the model.
+   */
   writeValue(value: any) {
     this.checked = !!value;
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Registers a callback to be triggered when the value has changed.
+   * Implemented as part of ControlValueAccessor.
+   * @param fn Function to be called on change.
+   */
   registerOnChange(fn: (value: any) => void) {
     this._controlValueAccessorChangeFn = fn;
   }
 
-  /** Implemented as part of ControlValueAccessor. */
+  /**
+   * Registers a callback to be triggered when the control has been touched.
+   * Implemented as part of ControlValueAccessor.
+   * @param fn Callback to be triggered when the checkbox is touched.
+   */
   registerOnTouched(fn: any) {
     this.onTouched = fn;
   }
 
-  /** Implemented as a part of ControlValueAccessor. */
+  /**
+   * Sets the checkbox's disabled state. Implemented as a part of ControlValueAccessor.
+   * @param isDisabled Whether the checkbox should be disabled.
+   */
   setDisabledState(isDisabled: boolean) {
     this.disabled = isDisabled;
   }

src/lib/chips/chip-list.spec.ts

@@ -47,9 +47,7 @@ describe('MdChipList', () => {
     });
 
     it('focuses the first chip on focus', () => {
-      let FOCUS_EVENT: Event = {} as Event;
-
-      chipListInstance.focus(FOCUS_EVENT);
+      chipListInstance.focus();
       fixture.detectChanges();
 
       expect(manager.focusedItemIndex).toBe(0);
@@ -109,15 +107,14 @@ describe('MdChipList', () => {
       });
 
       it('SPACE selects/deselects the currently focused chip', () => {
-        let FOCUS_EVENT: Event = {} as Event;
         let SPACE_EVENT: KeyboardEvent = new FakeEvent(SPACE) as KeyboardEvent;
         let firstChip: MdChip = chips.toArray()[0];
 
         spyOn(testComponent, 'chipSelect');
         spyOn(testComponent, 'chipDeselect');
 
         // Make sure we have the first chip focused
-        chipListInstance.focus(FOCUS_EVENT);
+        chipListInstance.focus();
 
         // Use the spacebar to select the chip
         chipListInstance._keydown(SPACE_EVENT);
@@ -144,14 +141,13 @@ describe('MdChipList', () => {
       });
 
       it('SPACE ignores selection', () => {
-        let FOCUS_EVENT: Event = {} as Event;
         let SPACE_EVENT: KeyboardEvent = new FakeEvent(SPACE) as KeyboardEvent;
         let firstChip: MdChip = chips.toArray()[0];
 
         spyOn(testComponent, 'chipSelect');
 
         // Make sure we have the first chip focused
-        chipListInstance.focus(FOCUS_EVENT);
+        chipListInstance.focus();
 
         // Use the spacebar to attempt to select the chip
         chipListInstance._keydown(SPACE_EVENT);

src/lib/chips/chip-list.ts

@@ -61,8 +61,7 @@ export class MdChipList implements AfterContentInit {
   /** The chip components contained within this chip list. */
   chips: QueryList<MdChip>;
 
-  constructor(private _elementRef: ElementRef) {
-  }
+  constructor(private _elementRef: ElementRef) { }
 
   ngAfterContentInit(): void {
     this._keyManager = new ListKeyManager(this.chips).withFocusWrap();
@@ -89,16 +88,15 @@ export class MdChipList implements AfterContentInit {
   }
 
   /**
-   * Programmatically focus the chip list. This in turn focuses the first non-disabled chip in this
-   * chip list.
-   *
-   * TODO: ARIA says this should focus the first `selected` chip.
+   * Programmatically focus the chip list. This in turn focuses the first
+   * non-disabled chip in this chip list.
    */
-  focus(event: Event) {
+  focus() {
+    // TODO: ARIA says this should focus the first `selected` chip.
     this._keyManager.focusFirstItem();
   }
 
-  /** Pass relevant key presses to our key manager. */
+  /** Passes relevant key presses to our key manager. */
   _keydown(event: KeyboardEvent) {
     switch (event.keyCode) {
       case SPACE:
@@ -190,7 +188,7 @@ export class MdChipList implements AfterContentInit {
    * Utility to ensure all indexes are valid.
    *
    * @param index The index to be checked.
-   * @returns {boolean} True if the index is valid for our list of chips.
+   * @returns True if the index is valid for our list of chips.
    */
   private _isValidIndex(index: number): boolean {
     return index >= 0 && index < this.chips.length;