docs(list): add example and missing JsDoc for selection-list (#6899)

Author: jelbourn

src/lib/list/list.md

@@ -42,6 +42,15 @@ element in an `<md-list-item>`.
 </md-nav-list>
 ```
 
+### Selection lists
+A selection list provides an interface for selecting values, where each list item is an option.
+
+<!-- example(list-selection) -->
+
+The options within a selection-list should not contain further interactive controls, such
+as buttons and anchors.
+
+
 ### Multi-line lists
 For lists that require multiple lines per item, annotate each line with an `mdLine` attribute.
 Whichever heading tag is appropriate for your DOM hierarchy should be used (not necessarily `<h3>`

src/lib/list/list.ts

@@ -33,6 +33,7 @@ export class MdListItemBase {}
 export const _MdListItemMixinBase = mixinDisableRipple(MdListItemBase);
 
 
+/** Divider between items within a list. */
 @Directive({
   selector: 'md-divider, mat-divider',
   host: {
@@ -42,6 +43,7 @@ export const _MdListItemMixinBase = mixinDisableRipple(MdListItemBase);
 })
 export class MdListDivider {}
 
+/** A Material Design list component. */
 @Component({
   moduleId: module.id,
   selector: 'md-list, mat-list, md-nav-list, mat-nav-list',
@@ -114,6 +116,7 @@ export class MdListIconCssMatStyler {}
 })
 export class MdListSubheaderCssMatStyler {}
 
+/** An item within a Material Design list. */
 @Component({
   moduleId: module.id,
   selector: 'md-list-item, mat-list-item, a[md-list-item], a[mat-list-item]',

src/lib/list/selection-list.ts

@@ -36,13 +36,15 @@ import {CanDisableRipple, mixinDisableRipple} from '../core/common-behaviors/dis
 import {MATERIAL_COMPATIBILITY_MODE} from '../core/compatibility/compatibility';
 
 
+/** @docs-private */
 export class MdSelectionListBase {}
 export const _MdSelectionListMixinBase = mixinDisableRipple(mixinDisabled(MdSelectionListBase));
 
+/** @docs-private */
 export class MdListOptionBase {}
 export const _MdListOptionMixinBase = mixinDisableRipple(MdListOptionBase);
 
-
+/** Event emitted by a selection-list whenever the state of an option is changed. */
 export interface MdSelectionListOptionEvent {
   option: MdListOption;
 }
@@ -95,10 +97,12 @@ export class MdListOption extends _MdListOptionMixinBase
   get disabled() { return (this.selectionList && this.selectionList.disabled) || this._disabled; }
   set disabled(value: any) { this._disabled = coerceBooleanProperty(value); }
 
+  /** Value of the option */
   @Input()
   get value() { return this._value; }
   set value( val: any) { this._value = coerceBooleanProperty(val); }
 
+  /** Whether the option is selected. */
   @Input()
   get selected() { return this._selected; }
   set selected( val: boolean) { this._selected = coerceBooleanProperty(val); }
@@ -135,6 +139,7 @@ export class MdListOption extends _MdListOptionMixinBase
     this.destroyed.emit({option: this});
   }
 
+  /** Toggles the selection state of the option. */
   toggle(): void {
     this.selected = !this.selected;
     this.selectionList.selectedOptions.toggle(this);
@@ -174,6 +179,9 @@ export class MdListOption extends _MdListOptionMixinBase
 }
 
 
+/**
+ * Material Design list component where each item is a selectable option. Behaves as a listbox.
+ */
 @Component({
   moduleId: module.id,
   selector: 'md-selection-list, mat-selection-list',
@@ -208,7 +216,7 @@ export class MdSelectionList extends _MdSelectionListMixinBase
   /** The option components contained within this selection-list. */
   @ContentChildren(MdListOption) options: QueryList<MdListOption>;
 
-  /** options which are selected. */
+  /** The currently selected options. */
   selectedOptions: SelectionModel<MdListOption> = new SelectionModel<MdListOption>(true);
 
   constructor(private _element: ElementRef) {
@@ -231,13 +239,12 @@ export class MdSelectionList extends _MdSelectionListMixinBase
     this._optionFocusSubscription.unsubscribe();
   }
 
+  /** Focus the selection-list. */
   focus() {
     this._element.nativeElement.focus();
   }
 
-  /**
-   * Map all the options' destroy event subscriptions and merge them into one stream.
-   */
+  /** Map all the options' destroy event subscriptions and merge them into one stream. */
   private _onDestroySubscription(): Subscription {
     return RxChain.from(this.options.changes)
       .call(startWith, this.options)
@@ -257,9 +264,7 @@ export class MdSelectionList extends _MdSelectionListMixinBase
       });
   }
 
-  /**
-   * Map all the options' onFocus event subscriptions and merge them into one stream.
-   */
+  /** Map all the options' onFocus event subscriptions and merge them into one stream. */
   private _onFocusSubscription(): Subscription {
     return RxChain.from(this.options.changes)
       .call(startWith, this.options)

src/material-examples/example-module.ts

@@ -52,6 +52,7 @@ import {InputOverviewExample} from './input-overview/input-overview-example';
 import {InputPrefixSuffixExample} from './input-prefix-suffix/input-prefix-suffix-example';
 import {ListOverviewExample} from './list-overview/list-overview-example';
 import {ListSectionsExample} from './list-sections/list-sections-example';
+import {ListSelectionExample} from './list-selection/list-selection-example';
 import {MenuIconsExample} from './menu-icons/menu-icons-example';
 import {MenuOverviewExample} from './menu-overview/menu-overview-example';
 import {PaginatorConfigurableExample} from './paginator-configurable/paginator-configurable-example';
@@ -323,6 +324,12 @@ export const EXAMPLE_COMPONENTS = {
     additionalFiles: null,
     selectorName: null
   },
+  'list-selection': {
+    title: 'List with selection',
+    component: ListSelectionExample,
+    additionalFiles: null,
+    selectorName: null
+  },
   'menu-icons': {
     title: 'Menu with icons',
     component: MenuIconsExample,
@@ -580,6 +587,7 @@ export const EXAMPLE_LIST = [
   InputPrefixSuffixExample,
   ListOverviewExample,
   ListSectionsExample,
+  ListSelectionExample,
   MenuIconsExample,
   MenuOverviewExample,
   PaginatorConfigurableExample,

src/material-examples/list-selection/list-selection-example.css

@@ -0,0 +1 @@
+/** No styles for this example. */

src/material-examples/list-selection/list-selection-example.html

@@ -0,0 +1,9 @@
+<md-selection-list #shoes>
+  <md-list-option *ngFor="let shoe of typesOfShoes">
+    {{shoe}}
+  </md-list-option>
+</md-selection-list>
+
+<p>
+  Options selected: {{shoes.selectedOptions.selected.length}}
+</p>

src/material-examples/list-selection/list-selection-example.ts

@@ -0,0 +1,13 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title List with selection
+ */
+@Component({
+  selector: 'list-selection-example',
+  styleUrls: ['list-selection-example.css'],
+  templateUrl: 'list-selection-example.html',
+})
+export class ListSelectionExample {
+  typesOfShoes = ['Boots', 'Clogs', 'Loafers', 'Moccasins', 'Sneakers'];
+}