docs(forms): updated forms docs to cover new apis

modules/angular2/src/forms/directives/ng_control_name.ts

@@ -13,44 +13,59 @@ const controlNameBinding =
     CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgControlName)}));
 
 /**
- * Binds a control with the specified name to a DOM element.
+ * Creates and binds a control with a specified name to a DOM element.
  *
+ * This directive can only be used as a child of {@link NgForm} or {@link NgFormModel}.
+
  * # Example
  *
- * In this example, we bind the login control to an input element. When the value of the input
- * element
- * changes, the value of
- * the control will reflect that change. Likewise, if the value of the control changes, the input
- * element reflects that
- * change.
- *
- * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g.
- * `NgControl`, `ControlGroupDirective`. This is just a shorthand for the same end result.
+ * In this example, we create the login and password controls.
+ * We can work with each control separately: check its validity, get its value, listen to its
+ changes.
  *
  *  ```
  * @Component({selector: "login-comp"})
  * @View({
  *      directives: [formDirectives],
- *      template:
- *              "<form [ng-form-model]='loginForm'>" +
- *              "Login <input type='text' ng-control='login'>" +
- *              "<button (click)="onLogin()">Login</button>" +
- *              "</form>"
- *      })
+ *      template: `
+ *              <form #f="form" (submit)='onLogIn(f.value)'>
+ *                Login <input type='text' ng-control='login' #l="form">
+ *                <div *ng-if="!l.valid">Login is invalid</div>
+ *
+ *                Password <input type='password' ng-control='password'>
+
+ *                <button type='submit'>Log in!</button>
+ *              </form>
+ *      `})
  * class LoginComp {
- *  loginForm:ControlGroup;
- *
- *  constructor() {
- *    this.loginForm = new ControlGroup({
- *      login: new Control(""),
- *    });
- *  }
- *
- *  onLogin() {
- *    // this.loginForm.value
+ *  onLogIn(value) {
+ *    // value === {login: 'some login', password: 'some password'}
  *  }
  * }
+ *  ```
  *
+ * We can also use ng-model to bind a domain model to the form.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [formDirectives],
+ *      template: `
+ *              <form (submit)='onLogIn()'>
+ *                Login <input type='text' ng-control='login' [(ng-model)]="credentials.login">
+ *                Password <input type='password' ng-control='password'
+ [(ng-model)]="credentials.password">
+ *                <button type='submit'>Log in!</button>
+ *              </form>
+ *      `})
+ * class LoginComp {
+ *  credentials: {login:string, password:string};
+ *
+ *  onLogIn() {
+ *    // this.credentials.login === "some login"
+ *    // this.credentials.password === "some password"
+ *  }
+ * }
  *  ```
  *
  * @exportedAs angular2/forms