docs(core): Document NgFor.

Closes #4533

modules/angular2/src/core/directives/ng_for.ts

@@ -13,31 +13,49 @@ import {isPresent, isBlank} from 'angular2/src/core/facade/lang';
  * each instantiated template inherits from the outer context with the given loop variable set
  * to the current item from the iterable.
  *
- * It is possible to alias the `index` to a local variable that will be set to the current loop
+ * # Local Variables
- * iteration in the template context, and also to alias the 'last' to a local variable that will
+ *
- * be set to a boolean indicating if the item is the last one in the iteration
+ * `NgFor` provides several exported values that can be aliased to local variables:
+ *
+ * * `index` will be set to the current loop iteration for each template context.
+ * * `last` will be set to a boolean value indicating whether the item is the last one in the
+ *   iteration.
+ * * `even` will be set to a boolean value indicating whether this item has an even index.
+ * * `odd` will be set to a boolean value indicating whether this item has an odd index.
+ *
+ * # Change Propagation
  *
  * When the contents of the iterator changes, `NgFor` makes the corresponding changes to the DOM:
  *
  * * When an item is added, a new instance of the template is added to the DOM.
  * * When an item is removed, its template instance is removed from the DOM.
  * * When items are reordered, their respective templates are reordered in the DOM.
+ * * Otherwise, the DOM element for that item will remain the same.
  *
- * ### Example
+ * Angular uses object identity to track insertions and deletions within the iterator and reproduce
+ * those changes in the DOM. This has important implications for animations and any stateful
+ * controls
+ * (such as `<input>` elements which accept user input) that are present. Inserted rows can be
+ * animated in, deleted rows can be animated out, and unchanged rows retain any unsaved state such
+ * as user input.
  *
- * ```
+ * It is possible for the identities of elements in the iterator to change while the data does not.
- * <ul>
+ * This can happen, for example, if the iterator produced from an RPC to the server, and that
- *   <li *ng-for="#error of errors; #i = index">
+ * RPC is re-run. Even if the data hasn't changed, the second response will produce objects with
- *     Error {{i}} of {{errors.length}}: {{error.message}}
+ * different identities, and Angular will tear down the entire DOM and rebuild it (as if all old
- *   </li>
+ * elements were deleted and all new elements inserted). This is an expensive operation and should
- * </ul>
+ * be avoided if possible.
- * ```
  *
- *##Syntax
+ * # Syntax
  *
  * - `<li *ng-for="#item of items; #i = index">...</li>`
  * - `<li template="ng-for #item of items; #i = index">...</li>`
  * - `<template ng-for #item [ng-for-of]="items" #i="index"><li>...</li></template>`
+ *
+ * ### Example
+ *
+ * See a [live demo](http://plnkr.co/edit/KVuXxDp0qinGDyo307QW?p=preview) for a more detailed
+ * example.
  */
 @Directive({selector: '[ng-for][ng-for-of]', inputs: ['ngForOf', 'ngForTemplate']})
 export class NgFor implements DoCheck {