From d630d5baa56ebc374cacef2d96305b241e71b870 Mon Sep 17 00:00:00 2001
From: Naomi Black <naomitraveller@gmail.com>
Date: Tue, 14 Apr 2015 14:16:14 -0700
Subject: [PATCH] docs(change_detection): document LifeCycle

---
 .../src/core/life_cycle/life_cycle.js         | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/modules/angular2/src/core/life_cycle/life_cycle.js b/modules/angular2/src/core/life_cycle/life_cycle.js
index 91b508b227..2e08d5af19 100644
--- a/modules/angular2/src/core/life_cycle/life_cycle.js
+++ b/modules/angular2/src/core/life_cycle/life_cycle.js
@@ -5,6 +5,29 @@ import {ExceptionHandler} from 'angular2/src/core/exception_handler';
 import {isPresent} from 'angular2/src/facade/lang';
 
 /**
+ * Provides access to explicitly trigger change detection in an application.
+ *
+ * By default, [Zone] triggers change detection in Angular on each virtual machine (VM) turn. When testing, or in some
+ * limited application use cases, a developer can also trigger change detection with the `lifecycle.tick()` method.
+ *
+ * Each Angular application has a single `LifeCycle` instance.
+ *
+ * # Example
+ *
+ * This is a contrived example, since the bootstrap automatically runs inside of the [Zone], which invokes
+ * `lifecycle.tick()` on your behalf.
+ *
+ * ```javascript
+ * bootstrap(MyApp).then((ref:ComponentRef) => {
+ *   var lifeCycle = ref.injector.get(LifeCycle);
+ *   var myApp = ref.instance;
+ *
+ *   ref.doSomething();
+ *   lifecycle.tick();
+ * });
+ * ```
+ *
+ *
  * @exportedAs angular2/change_detection
  */
 @Injectable()
@@ -33,6 +56,16 @@ export class LifeCycle {
     });
   }
 
+  /**
+   *  Invoke this method to explicitly process change detection and its side-effects.
+   *
+   *  In development mode, `tick()` also performs a second change detection cycle to ensure that no further
+   *  changes are detected. If additional changes are picked up during this second cycle, bindings in the app have
+   *  side-effects that cannot be resolved in a single change detection pass. In this case, Angular throws an error,
+   *  since an Angular application can only have one change detection pass during which all change detection must
+   *  complete.
+   *
+   */
   tick() {
     this._changeDetector.detectChanges();
     if (this._enforceNoNewChanges) {