fix(api): updates the api to standard naming and adds docs for selection

src/cdk/collections/collections.md

@@ -1,3 +1,34 @@
-### Collections
+The `collections` package provides a set of utilities for managing collections.
 
-A set of utilities for managing collections.
+### `SelectionModel`
+`SelectionModel` is a utility for powering selection of one or more options from a list.
+This model is used in components such as the selection list, table selections and chip lists.
+
+#### Basic Usage
+```javascript
+const model = new SelectionModel(
+  true,   // multiple selection or not
+  [2,1,3] // initial selected values
+);
+
+// select a value
+model.select(4);
+console.log(model.selected.length) //->  4
+
+// deselect a value
+model.deselect(4);
+console.log(model.selected.length) //->  3
+
+// toggle a value
+model.toggle(4);
+console.log(model.selected.length) //->  4
+
+// check for selection
+console.log(model.isSelected(4)) //-> true
+
+// sort the selections
+console.log(model.sort()) //-> [1,2,3,4]
+
+// listen for changes
+model.changes.subscribe(s => console.log(s));
+```

src/cdk/collections/selection.spec.ts

@@ -43,7 +43,7 @@ describe('SelectionModel', () => {
     it('should be able to select multiple options', () => {
       const onChangeSpy = jasmine.createSpy('onChange spy');
 
-      model.onChange!.subscribe(onChangeSpy);
+      model.changed!.subscribe(onChangeSpy);
       model.select(1);
       model.select(2);
 
@@ -56,7 +56,7 @@ describe('SelectionModel', () => {
     it('should be able to select multiple options at the same time', () => {
       const onChangeSpy = jasmine.createSpy('onChange spy');
 
-      model.onChange!.subscribe(onChangeSpy);
+      model.changed!.subscribe(onChangeSpy);
       model.select(1, 2);
 
       expect(model.selected.length).toBe(2);
@@ -112,7 +112,7 @@ describe('SelectionModel', () => {
 
       model.select(1);
 
-      model.onChange!.subscribe(spy);
+      model.changed!.subscribe(spy);
 
       model.select(2);
 
@@ -144,7 +144,7 @@ describe('SelectionModel', () => {
         model = new SelectionModel(true);
         spy = jasmine.createSpy('SelectionModel change event');
 
-        model.onChange!.subscribe(spy);
+        model.changed!.subscribe(spy);
       });
 
       it('should emit an event when a value is selected', () => {
@@ -167,7 +167,7 @@ describe('SelectionModel', () => {
       it('should not emit an event when preselecting values', () => {
         model = new SelectionModel(false, [1]);
         spy = jasmine.createSpy('SelectionModel initial change event');
-        model.onChange!.subscribe(spy);
+        model.changed!.subscribe(spy);
 
         expect(spy).not.toHaveBeenCalled();
       });
@@ -181,7 +181,7 @@ describe('SelectionModel', () => {
         model = new SelectionModel(true, [1, 2, 3]);
         spy = jasmine.createSpy('SelectionModel change event');
 
-        model.onChange!.subscribe(spy);
+        model.changed!.subscribe(spy);
       });
 
       it('should emit an event when a value is deselected', () => {
@@ -218,7 +218,7 @@ describe('SelectionModel', () => {
     });
 
     it('should not have an onChange stream if change events are disabled', () => {
-      expect(model.onChange).toBeFalsy();
+      expect(model.changed).toBeFalsy();
     });
 
     it('should still update the select value', () => {

src/cdk/collections/selection.ts

@@ -34,7 +34,14 @@ export class SelectionModel<T> {
   }
 
   /** Event emitted when the value has changed. */
-  onChange: Subject<SelectionChange<T>> | null = this._emitChanges ? new Subject() : null;
+  changed: Subject<SelectionChange<T>> | null = this._emitChanges ? new Subject() : null;
+
+  /**
+   * Event emitted when the value has changed.
+   * @deprecated Use `changed` instead.
+   * @deletion-target 8.0.0 To be changed to `changed`
+   */
+  onChange: Subject<SelectionChange<T>> | null = this.changed;
 
   constructor(
     private _multiple = false,
@@ -129,8 +136,8 @@ export class SelectionModel<T> {
     this._selected = null;
 
     if (this._selectedToEmit.length || this._deselectedToEmit.length) {
-      if (this.onChange) {
-        this.onChange.next({
+      if (this.changed) {
+        this.changed.next({
           source: this,
           added: this._selectedToEmit,
           removed: this._deselectedToEmit