doc(Lifecycle events): Document the call order

modules/angular2/src/core/annotations_impl/annotations.ts

@@ -1037,7 +1037,13 @@ export class Component extends Directive {
   }
 }
 
-
+/**
+ * Lifecycle events are guaranteed to be called in the following order:
+ * - `onChange` (optional if any bindings have changed),
+ * - `onInit` (optional after the first check only),
+ * - `onCheck`,
+ * - `onAllChangesDone`
+ */
 @CONST()
 export class LifecycleEvent {
   constructor(public name: string) {}
@@ -1150,7 +1156,8 @@ export const onCheck = CONST_EXPR(new LifecycleEvent("onCheck"));
 export const onInit = CONST_EXPR(new LifecycleEvent("onInit"));
 
 /**
- * Notify a directive when the bindings of all its children have been changed.
+ * Notify a directive when the bindings of all its children have been checked (whether they have
+ * changed or not).
  *
  * ## Example:
  *

modules/angular2/test/core/directive_lifecycle_integration_spec.ts

@@ -14,7 +14,15 @@ import {
 
 import {ListWrapper} from 'angular2/src/facade/collection';
 import {TestBed} from 'angular2/src/test_lib/test_bed';
-import {Directive, Component, View, onCheck, onInit, onChange} from 'angular2/angular2';
+import {
+  Directive,
+  Component,
+  View,
+  onCheck,
+  onInit,
+  onChange,
+  onAllChangesDone
+} from 'angular2/angular2';
 import * as viewAnn from 'angular2/src/core/annotations_impl/view';
 
 export function main() {
@@ -23,7 +31,7 @@ export function main() {
 
     beforeEach(() => { ctx = new MyComp(); });
 
-    it('should invoke lifecycle methods onChanges > onInit > onCheck',
+    it('should invoke lifecycle methods onChange > onInit > onCheck > onAllChangesDone',
        inject([TestBed, AsyncTestCompleter], (tb, async) => {
          tb.overrideView(
              MyComp,
@@ -35,11 +43,18 @@ export function main() {
                var dir = view.rawView.elementInjectors[0].get(LifecycleDir);
                view.detectChanges();
 
-               expect(dir.log).toEqual(["onChanges", "onInit", "onCheck"]);
+               expect(dir.log).toEqual(["onChange", "onInit", "onCheck", "onAllChangesDone"]);
 
                view.detectChanges();
 
-               expect(dir.log).toEqual(["onChanges", "onInit", "onCheck", "onCheck"]);
+               expect(dir.log).toEqual([
+                 "onChange",
+                 "onInit",
+                 "onCheck",
+                 "onAllChangesDone",
+                 "onCheck",
+                 "onAllChangesDone"
+               ]);
 
                async.done();
              });
@@ -48,18 +63,24 @@ export function main() {
 }
 
 
-@Directive({selector: "[lifecycle]", properties: ['field'], lifecycle: [onChange, onCheck, onInit]})
+@Directive({
+  selector: "[lifecycle]",
+  properties: ['field'],
+  lifecycle: [onChange, onCheck, onInit, onAllChangesDone]
+})
 class LifecycleDir {
   field;
   log: List<string>;
 
   constructor() { this.log = []; }
 
-  onChange(_) { ListWrapper.push(this.log, "onChanges"); }
+  onChange(_) { ListWrapper.push(this.log, "onChange"); }
 
   onInit() { ListWrapper.push(this.log, "onInit"); }
 
   onCheck() { ListWrapper.push(this.log, "onCheck"); }
+
+  onAllChangesDone() { ListWrapper.push(this.log, "onAllChangesDone"); }
 }
 
 @Component({selector: 'my-comp'})