docs(change_detection): add docs to change detection exceptions

Author: vsavkin

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.'); }