From 0e61a86763e14999be91ff4c1d5c1fc9c8c3ac0f Mon Sep 17 00:00:00 2001
From: Nick Van Dyck <vandyck.nick@outlook.com>
Date: Thu, 19 Mar 2015 14:31:41 +0100
Subject: [PATCH] docs: annotations

---
 modules/angular2/docs/core/01_templates.md    | 43 ++++++-----
 .../src/core/annotations/annotations.js       | 72 +++++++++++--------
 2 files changed, 69 insertions(+), 46 deletions(-)

diff --git a/modules/angular2/docs/core/01_templates.md b/modules/angular2/docs/core/01_templates.md
index 5574ed65de..0519df7d4e 100644
--- a/modules/angular2/docs/core/01_templates.md
+++ b/modules/angular2/docs/core/01_templates.md
@@ -187,7 +187,7 @@ Example:
 <pre>
 ```
 <ul>
-  <li template="foreach: #item in items">
+  <li template="for: #item of items">
     {{item}}
   </li>
 </ul>
@@ -201,8 +201,8 @@ Example:
 <pre>
 ```
 <ul>
-  <template def-foreach:"item"
-            bind-foreach-in="items">
+  <template def-for:"item"
+            bind-for-in="items">
     <li>
       {{item}}
     </li>
@@ -221,8 +221,8 @@ Example:
 
 <pre>
 ```
-<template #foreach="item"
-          [foreach-in]="items">
+<template #for="item"
+          [for-in]="items">
   _some_content_to_repeat_
 </template>
 ```
@@ -234,8 +234,8 @@ Example:
 Example:
 <pre>
 ```
-<template def-foreach="item"
-          bind-foreach-in="items">
+<template def-for="item"
+          bind-for-in="items">
   _some_content_to_repeat_
 </template>
 ```
@@ -408,22 +408,22 @@ NOTE: Only Viewport directives can be placed on the template element. (Decorator
 ### Template Microsyntax
 
 Often times it is necessary to encode a lot of different bindings into a template to control how the instantiation
-of the templates occurs. One such example is `foreach`.
+of the templates occurs. One such example is `for`.
 
 ```
 <form #foo=form>
 </form>
 <ul>
-  <template foreach #person [in]="people" #i="index">
+  <template for #person [in]="people" #i="index">
     <li>{{i}}. {{person}}<li>
   </template>
 </ul>
 ```
 
 Where:
-* `foreach` triggers the foreach directive.
-* `[in]="people"` binds an iterable object to the `foreach` controller.
-* `#person` exports the implicit `foreach` item.
+* `for` triggers the for directive.
+* `[in]="people"` binds an iterable object to the `for` controller.
+* `#person` exports the implicit `for` item.
 * `#i=index` exports item index as `i`.
 
 The above example is explicit but quite wordy. For this reason in most situations a short hand version of the
@@ -431,7 +431,7 @@ syntax is preferable.
 
 ```
 <ul>
-  <li template="foreach; #person; in=people; #i=index;">{{i}}. {{person}}<li>
+  <li template="for; #person; in=people; #i=index;">{{i}}. {{person}}<li>
 </ul>
 ```
 
@@ -441,19 +441,28 @@ which allows us to further shorten the text.
 
 ```
 <ul>
-  <li template="foreach #person in people #i=index">{{i}}. {{person}}<li>
+  <li template="for #person of people #i=index">{{i}}. {{person}}<li>
 </ul>
 ```
 
-We can also optionally use `var` instead of `#` and add `:` to `foreach` which creates the following recommended
-microsyntax for `foreach`.
+We can also optionally use `var` instead of `#` and add `:` to `for` which creates the following recommended
+microsyntax for `for`.
 
 ```
 <ul>
-  <li template="foreach: var person in people; var i=index">{{i}}. {{person}}<li>
+  <li template="for: var person of people; var i=index">{{i}}. {{person}}<li>
 </ul>
 ```
 
+Finally, we can move the `for` keyword to the left hand side and prefix it with `*` as so:
+
+```
+<ul>
+  <li *for="var person of people; var i=index">{{i}}. {{person}}<li>
+</ul>
+```
+
+
 The format is intentionally defined freely, so that developers of directives can build an expressive microsyntax for
 their directives. The following code describes a more formal definition.
 
diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js
index 8b8ce8c65a..ac845cb265 100644
--- a/modules/angular2/src/core/annotations/annotations.js
+++ b/modules/angular2/src/core/annotations/annotations.js
@@ -556,7 +556,7 @@ export class Component extends Directive {
 }
 
 /**
- * A directive used for dynamically loading components.
+ * Directive used for dynamically loading components.
  *
  * Regular angular components are statically resolved. DynamicComponent allows to you resolve a component at runtime
  * instead by providing a placeholder into which a regular angular component can be dynamically loaded. Once loaded,
@@ -637,9 +637,9 @@ export class DynamicComponent extends Directive {
 /**
  * Directive that attaches behavior to DOM elements.
  *
- * A decorator directive attaches behavior to a DOM element in a composable manner. 
+ * A decorator directive attaches behavior to a DOM element in a composable manner.
  * (see: http://en.wikipedia.org/wiki/Composition_over_inheritance)
- * 
+ *
  * Decorators:
  * - are simplest form of [Directive]s.
  * - are best used as a composition pattern ()
@@ -652,7 +652,7 @@ export class DynamicComponent extends Directive {
  *
  * ## Example
  *
- * Here we use a decorator directive to simply define basic tool-tip behavior. 
+ * Here we use a decorator directive to simply define basic tool-tip behavior.
  *
  * ```
  * @Decorator({
@@ -685,9 +685,9 @@ export class DynamicComponent extends Directive {
  *   }
  * }
  * ```
- * In our HTML template, we can then add this behavior to a `<div>` or any other element with the `tooltip` selector, 
+ * In our HTML template, we can then add this behavior to a `<div>` or any other element with the `tooltip` selector,
  * like so:
- * 
+ *
  *  ```
  * <div tooltip="some text here"></div>
  * ```
@@ -728,24 +728,45 @@ export class Decorator extends Directive {
 }
 
 /**
- * Viewport is used for controlling the instatiation of inline templates. [TODO: needs co-work :)]
+ * Directive that controls the instantiation, destruction, and positioning of inline template elements.
  *
- * Viewport consist of a controller which can inject [ViewContainer]. A [ViewContainer] represents a location in the
- * current view where child views can be inserted. [ViewContainer] is created as a result of `<template>` element.
+ * A viewport directive uses a [ViewContainer] to instantiate, insert, move, and destroy views at runtime.
+ * The [ViewContainer] is created as a result of `<template>` element, and represents a location in the current view
+ * where these actions are performed.
  *
- * NOTE: `<template>` directives can be created in shorthand form as `<TAG template="...">` or `<TAG *key="...">`
+ * Views are always created as children of the current [View], and as siblings of the `<template>` element. Thus a
+ * directive in a child view cannot inject the viewport directive that created it.
  *
- * ## Example
+ * Since viewport directives are common in Angular, and using the full `<template>` element syntax is wordy, Angular
+ * also supports a shorthand notation: `<li *foo="bar">` and `<li template="foo: bar">` are equivalent.
  *
- * Given folowing inline template, let's implement the `unless` behavior.
+ * Thus,
  *
  * ```
  * <ul>
- *   <li *unless="expr"></li>
+ *   <li *foo="bar" title="text"></li>
  * </ul>
  * ```
  *
- * Can be implemented using:
+ * Expands in use to:
+ *
+ * ```
+ * <ul>
+ *   <template [foo]="bar">
+ *     <li title="text"></li>
+ *   </template>
+ * </ul>
+ * ```
+ *
+ * Notice that although the shorthand places `*foo="bar"` within the `<li>` element, the binding for the `Viewport`
+ * controller is correctly instantiated on the `<template>` element rather than the `<li>` element.
+ *
+ *
+ * ## Example
+ *
+ * Let's suppose we want to implement the `unless` behavior, to conditionally include a template.
+ *
+ * Here is a simple viewport directive that triggers on an `unless` selector:
  *
  * ```
  * @Viewport({
@@ -754,7 +775,7 @@ export class Decorator extends Directive {
  *     'condition': 'unless'
  *   }
  * })
- * export class If {
+ * export class Unless {
  *   viewContainer: ViewContainer;
  *   prevCondition: boolean;
  *
@@ -775,20 +796,14 @@ export class Decorator extends Directive {
  * }
  * ```
  *
- * To better undarstand what is hapening, remember that angular converts the above template to:
- *
+ * We can then use this `unless` selector in a template:
  * ```
  * <ul>
- *   <template [unless]="exp">
- *     <li></li>
- *   </template>
+ *   <li *unless="expr"></li>
  * </ul>
  * ```
  *
- * Notice that the `*unless="exp"` got hoisted to `<template>`. This means that the `Viewport` controller is instantiated
- * on the `<template>` element rather thna the `<li>` element.
- *
- * Once the viewport insntantiates the child view the result is:
+ * Once the viewport instantiates the child view, the shorthand notation for the template expands and the result is:
  *
  * ```
  * <ul>
@@ -799,9 +814,8 @@ export class Decorator extends Directive {
  * </ul>
  * ```
  *
- * The key thing to notice here is that `<li>` instance is a sibling of `<template>` not a child. For this reason
- * it is not possible to inject `Viewport` directive into other directives, (`Viweport` directives are always on
- * `<template>` elements which are leafs.)
+ * Note also that although the `<li></li>` template still exists inside the `<template></template>`, the instantiated
+ * view occurs on the second `<li></li>` which is a sibling to the `<template>` element.
  *
  *
  * @publicModule angular2/annotations
@@ -831,7 +845,7 @@ export class Viewport extends Directive {
 //TODO(misko): turn into LifecycleEvent class once we switch to TypeScript;
 
 /**
- * Specify that a directive should be notified whenever a [View] that contains it is destroyed.
+ * Notify a directive whenever a [View] that contains it is destroyed.
  *
  * ## Example
  *
@@ -852,7 +866,7 @@ export const onDestroy = "onDestroy";
 
 
 /**
- * Specify that a directive should be notified when any of its bindings have changed.
+ * Notify a directive when any of its bindings have changed.
  *
  * ## Example:
  *