From 9d2d674ef897e96b92e036b3b9ece30981248de3 Mon Sep 17 00:00:00 2001
From: vsavkin <avix1000@gmail.com>
Date: Tue, 22 Sep 2015 14:36:07 -0700
Subject: [PATCH] docs(change_detection): add docs to change detection
 exceptions

---
 .../src/core/change_detection/exceptions.ts   | 68 +++++++++++++++++--
 1 file changed, 61 insertions(+), 7 deletions(-)

diff --git a/modules/angular2/src/core/change_detection/exceptions.ts b/modules/angular2/src/core/change_detection/exceptions.ts
index c1f0b7c7d6..f440045616 100644
--- a/modules/angular2/src/core/change_detection/exceptions.ts
+++ b/modules/angular2/src/core/change_detection/exceptions.ts
@@ -3,11 +3,35 @@ import {BaseException, WrappedException} from "angular2/src/core/facade/exceptio
 /**
  * An error thrown if application changes model breaking the top-down data flow.
  *
- * Angular expects that the data flows from top (root) component to child (leaf) components.
- * This is known as directed acyclic graph. This allows Angular to only execute change detection
- * once and prevents loops in change detection data flow.
- *
  * This exception is only thrown in dev mode.
+ *
+ * <!-- TODO: Add a link once the dev mode option is configurable -->
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @Component({selector: 'parent'})
+ * @View({
+ *   template: `
+ *     <child [prop]="parentProp"></child>
+ *   `,
+ *   directives: [forwardRef(() => Child)]
+ * })
+ * class Parent {
+ *   parentProp = "init";
+ * }
+ *
+ * @Directive({selector: 'child', properties: ['prop']})
+ * class Child {
+ *   constructor(public parent: Parent) {}
+ *
+ *   set prop(v) {
+ *     // this updates the parent property, which is disallowed during change detection
+ *     // this will result in ExpressionChangedAfterItHasBeenCheckedException
+ *     this.parent.parentProp = "updated";
+ *   }
+ * }
+ * ```
  */
 export class ExpressionChangedAfterItHasBeenCheckedException extends BaseException {
   constructor(exp: string, oldValue: any, currValue: any, context: any) {
@@ -19,11 +43,39 @@ export class ExpressionChangedAfterItHasBeenCheckedException extends BaseExcepti
 /**
  * Thrown when an expression evaluation raises an exception.
  *
- * This error wraps the original exception, this is done to attach expression location information.
+ * This error wraps the original exception to attach additional contextual information that can
+ * be useful for debugging.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/2Kywoz?p=preview))
+ *
+ * ```typescript
+ * @Directive({selector: 'child', properties: ['prop']})
+ * class Child {
+ *   prop;
+ * }
+ *
+ * @Component({
+ *   selector: 'app'
+ * })
+ * @View({
+ *   template: `
+ *     <child [prop]="field.first"></child>
+ *   `,
+ *   directives: [Child]
+ * })
+ * class App {
+ *   field = null;
+ * }
+ *
+ * bootstrap(App);
+ * ```
+ *
+ * You can access the original exception and stack through the `originalException` and
+ * `originalStack` properties.
  */
 export class ChangeDetectionError extends WrappedException {
   /**
-   * Location of the expression.
+   * Information about the expression that triggered the exception.
    */
   location: string;
 
@@ -36,7 +88,9 @@ export class ChangeDetectionError extends WrappedException {
 /**
  * Thrown when change detector executes on dehydrated view.
  *
- * This is angular internal error.
+ * This error indicates a bug in the framework.
+ *
+ * This is an internal Angular error.
  */
 export class DehydratedException extends BaseException {
   constructor() { super('Attempt to detect changes on a dehydrated detector.'); }