docs(change_detection): add docs to ChangeDetectorRef

modules/angular2/src/core/change_detection/change_detector_ref.ts

@@ -2,10 +2,7 @@ import {ChangeDetector} from './interfaces';
 import {ChangeDetectionStrategy} from './constants';
 
 /**
- * Controls change detection.
+ * Reference to a component's change detection object.
- *
- * {@link ChangeDetectorRef} allows requesting checks for detectors that rely on observables. It
- * also allows detaching and attaching change detector subtrees.
  */
 export class ChangeDetectorRef {
   /**
@@ -14,7 +11,42 @@ export class ChangeDetectorRef {
   constructor(private _cd: ChangeDetector) {}
 
   /**
-   * Request to check all OnPush ancestors.
+   * Marks all {@link OnPush} ancestors as to be checked.
+   *
+   * <!-- TODO: Add a link to a chapter on OnPush components -->
+   *
+   * ### Example ([live demo](http://plnkr.co/edit/GC512b?p=preview))
+   *
+   * ```typescript
+   * @Component({selector: 'cmp', changeDetection: ChangeDetectionStrategy.OnPush})
+   * @View({template: `Number of ticks: {{numberOfTicks}}`})
+   * class Cmp {
+   *   numberOfTicks = 0;
+   *
+   *   constructor(ref: ChangeDetectorRef) {
+   *     setInterval(() => {
+   *       this.numberOfTicks ++
+   *       // the following is required, otherwise the view will not be updated
+   *       this.ref.markForCheck();
+   *     }, 1000);
+   *   }
+   * }
+   *
+   * @Component({
+   *   selector: 'app',
+   *   changeDetection: ChangeDetectionStrategy.OnPush
+   * })
+   * @View({
+   *   template: `
+   *     <cmp><cmp>
+   *   `,
+   *   directives: [Cmp]
+   * })
+   * class App {
+   * }
+   *
+   * bootstrap(App);
+   * ```
    */
   markForCheck(): void { this._cd.markPathToRootAsCheckOnce(); }
 
@@ -22,16 +54,141 @@ export class ChangeDetectorRef {
    * Detaches the change detector from the change detector tree.
    *
    * The detached change detector will not be checked until it is reattached.
+   *
+   * This can also be used in combination with {@link detectChanges} to implement local change
+   * detection checks.
+   *
+   * <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
+   * <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
+   *
+   * ### Example
+   *
+   * The following example defines a component with a large list of readonly data.
+   * Imagine the data changes constantly, many times per second. For performance reasons,
+   * we want to check and update the list every five seconds. We can do that by detaching
+   * the component's change detector and doing a local check every five seconds.
+   *
+   * ```typescript
+   * class DataProvider {
+   *   // in a real application the returned data will be different every time
+   *   get data() {
+   *     return [1,2,3,4,5];
+   *   }
+   * }
+   *
+   * @Component({selector: 'giant-list'})
+   * @View({
+   *   template: `
+   *     <li *ng-for="#d of dataProvider.data">Data {{d}}</lig>
+   *   `,
+   *   directives: [NgFor]
+   * })
+   * class GiantList {
+   *   constructor(private ref: ChangeDetectorRef, private dataProvider:DataProvider) {
+   *     ref.detach();
+   *     setInterval(() => {
+   *       this.ref.detectChanges();
+   *     }, 5000);
+   *   }
+   * }
+   *
+   * @Component({
+   *   selector: 'app', bindings: [DataProvider]
+   * })
+   * @View({
+   *   template: `
+   *     <giant-list><giant-list>
+   *   `,
+   *   directives: [GiantList]
+   * })
+   * class App {
+   * }
+   *
+   * bootstrap(App);
+   * ```
    */
   detach(): void { this._cd.mode = ChangeDetectionStrategy.Detached; }
 
+  /**
+   * Checks the change detector and its children.
+   *
+   * This can also be used in combination with {@link detach} to implement local change detection
+   * checks.
+   *
+   * <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
+   * <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
+   *
+   * ### Example
+   *
+   * The following example defines a component with a large list of readonly data.
+   * Imagine, the data changes constantly, many times per second. For performance reasons,
+   * we want to check and update the list every five seconds.
+   *
+   * We can do that by detaching the component's change detector and doing a local change detection
+   * check
+   * every five seconds.
+   *
+   * See {@link detach} for more information.
+   */
   detectChanges(): void { this._cd.detectChanges(); }
 
   /**
    * Reattach the change detector to the change detector tree.
    *
-   * This also requests a check of this change detector. This reattached change detector will be
+   * This also marks OnPush ancestors as to be checked. This reattached change detector will be
    * checked during the next change detection run.
+   *
+   * <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
+   *
+   * ### Example ([live demo](http://plnkr.co/edit/aUhZha?p=preview))
+   *
+   * The following example creates a component displaying `live` data. The component will detach
+   * its change detector from the main change detector tree when the component's live property
+   * is set to false.
+   *
+   * ```typescript
+   * class DataProvider {
+   *   data = 1;
+   *
+   *   constructor() {
+   *     setInterval(() => {
+   *       this.data = this.data * 2;
+   *     }, 500);
+   *   }
+   * }
+   *
+   * @Component({selector: 'live-data', properties: ['live']})
+   * @View({
+   *   template: `Data: {{dataProvider.data}}`
+   * })
+   * class LiveData {
+   *   constructor(private ref: ChangeDetectorRef, private dataProvider:DataProvider) {}
+   *
+   *   set live(value) {
+   *     if (value)
+   *       this.ref.reattach();
+   *     else
+   *       this.ref.detach();
+   *   }
+   * }
+   *
+   * @Component({
+   *   selector: 'app',
+   *   bindings: [DataProvider]
+   * })
+   * @View({
+   *   template: `
+   *     Live Update: <input type="checkbox" [(ng-model)]="live">
+   *     <live-data [live]="live"><live-data>
+   *   `,
+   *   directives: [LiveData, FORM_DIRECTIVES]
+   * })
+   * class App {
+   *   live = true;
+   * }
+   *
+   * bootstrap(App);
+   * ```
    */
   reattach(): void {
     this._cd.mode = ChangeDetectionStrategy.CheckAlways;

modules/angular2/test/public_api_spec.ts

@@ -544,18 +544,9 @@ var NG_API = [
   'KeyValueDiffers',
   'KeyValueDiffers.factories',
   'KeyValueDiffers.find()',
-  'LifeCycle',
+  'LifeCycle',  // TODO: replace with ApplicationRef
   'LifeCycle.registerWith()',
   'LifeCycle.tick()',
-  'Locals',
-  'Locals.clearValues()',
-  'Locals.contains()',
-  'Locals.current',
-  'Locals.current=',
-  'Locals.get()',
-  'Locals.parent',
-  'Locals.parent=',
-  'Locals.set()',
   'LowerCasePipe',
   'LowerCasePipe.transform()',
   'MAX_IN_MEMORY_ELEMENTS_PER_TEMPLATE',