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

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

@@ -5,7 +5,6 @@ import {ControlValueAccessor} from './control_value_accessor';
 /**
  * The accessor for writing a value and listening to changes on a checkbox input element.
  *
- *
  *  # Example
  *  ```
  *  <input type="checkbox" [ng-control]="rememberLogin">

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

@@ -4,7 +4,7 @@ import {List} from 'angular2/src/facade/collection';
 /**
  * A directive that contains a group of [NgControl].
  *
- * @exportedAs angular2/forms
+ * Only used by the forms module.
  */
 export class ControlContainer {
   name: string;

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

@@ -1,3 +1,8 @@
+/**
+ * A bridge between a control and a native element.
+ *
+ * Please see {@link DefaultValueAccessor} for more information.
+ */
 export interface ControlValueAccessor {
   writeValue(obj: any): void;
   registerOnChange(fn: any): void;

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

@@ -4,14 +4,12 @@ import {ControlValueAccessor} from './control_value_accessor';
 import {isBlank} from 'angular2/src/facade/lang';
 
 /**
- * The default accessor for writing a value and listening to changes that is used by a
- * {@link Control} directive.
- *
- * This is the default strategy that Angular uses when no other accessor is applied.
+ * The default accessor for writing a value and listening to changes that is used by the
+ * {@link NgModel}, {@link NgFormControl}, and {@link NgControlName} directives.
  *
  *  # Example
  *  ```
- *  <input type="text" [ng-form-control]="loginControl">
+ *  <input type="text" [(ng-model)]="searchQuery">
  *  ```
  *
  * @exportedAs angular2/forms

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

@@ -2,6 +2,11 @@ import {NgControl} from './ng_control';
 import {NgControlGroup} from './ng_control_group';
 import {Control} from '../model';
 
+/**
+ * An interface that {@link NgFormModel} and {@link NgForm} implement.
+ *
+ * Only used by the forms module.
+ */
 export interface Form {
   addControl(dir: NgControl): void;
   removeControl(dir: NgControl): void;

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

@@ -3,7 +3,9 @@ import {Validators} from '../validators';
 import {Control} from '../model';
 
 /**
- * A directive that bind a [ng-control] object to a DOM element.
+ * An abstract class that all control directive extend.
+ *
+ * It binds a {@link Control} object to a DOM element.
  *
  * @exportedAs angular2/forms
  */

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

@@ -10,43 +10,37 @@ const controlGroupBinding =
     CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgControlGroup)}));
 
 /**
- * Binds a ng-control group to a DOM element.
+ * Creates and binds a control group to a DOM element.
+ *
+ * This directive can only be used as a child of {@link NgForm} or {@link NgFormModel}.
  *
  * # Example
  *
- * In this example, we create a ng-control group, and we bind the login and
- * password controls to the login and password elements.
- *
- * 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 credentials and personal control groups.
+ * We can work with each group separately: check its validity, get its value, listen to its changes.
  *
  *  ```
- * @Component({selector: "login-comp"})
+ * @Component({selector: "signup-comp"})
  * @View({
  *      directives: [formDirectives],
- *      template:
- *              "<form [ng-form-model]='loginForm'>" +
- *              "<div ng-control-group="credentials">
- *              "Login <input type='text' ng-control='login'>" +
- *              "Password <input type='password' ng-control='password'>" +
- *              "<button (click)="onLogin()">Login</button>" +
- *              "</div>"
- *              "</form>"
- *      })
- * class LoginComp {
- *  loginForm:ControlGroup;
+ *      template: `
+ *              <form #f="form" (submit)='onSignUp(f.value)'>
+ *                <div ng-control-group='credentials' #credentials="form">
+ *                  Login <input type='text' ng-control='login'>
+ *                  Password <input type='password' ng-control='password'>
+ *                </div>
+ *                <div *ng-if="!credentials.valid">Credentials are invalid</div>
  *
- *  constructor() {
- *    this.loginForm = new ControlGroup({
- *      credentials: new ControlGroup({
- *        login: new Cntrol(""),
- *        password: new Control("")
- *      })
- *    });
- *  }
- *
- *  onLogin() {
- *    // this.loginForm.value
+ *                <div ng-control-group='personal'>
+ *                  Name <input type='text' ng-control='name'>
+ *                </div>
+ *                <button type='submit'>Sign Up!</button>
+ *              </form>
+ *      `})
+ * class SignupComp {
+ *  onSignUp(value) {
+ *    // value === {personal: {name: 'some name'},
+ *    //  credentials: {login: 'some login', password: 'some password'}}
  *  }
  * }
  *

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

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

@@ -13,6 +13,40 @@ import {setUpControl} from './shared';
 const formDirectiveBinding =
     CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgForm)}));
 
+/**
+ * Creates and binds a form object to a DOM element.
+ *
+ * # Example
+ *
+ *  ```
+ * @Component({selector: "signup-comp"})
+ * @View({
+ *      directives: [formDirectives],
+ *      template: `
+ *              <form #f="form" (submit)='onSignUp(f.value)'>
+ *                <div ng-control-group='credentials' #credentials="form">
+ *                  Login <input type='text' ng-control='login'>
+ *                  Password <input type='password' ng-control='password'>
+ *                </div>
+ *                <div *ng-if="!credentials.valid">Credentials are invalid</div>
+ *
+ *                <div ng-control-group='personal'>
+ *                  Name <input type='text' ng-control='name'>
+ *                </div>
+ *                <button type='submit'>Sign Up!</button>
+ *              </form>
+ *      `})
+ * class SignupComp {
+ *  onSignUp(value) {
+ *    // value === {personal: {name: 'some name'},
+ *    //  credentials: {login: 'some login', password: 'some password'}}
+ *  }
+ * }
+ *
+ *  ```
+ *
+ * @exportedAs angular2/forms
+ */
 @Directive({
   selector: 'form:not([ng-no-form]):not([ng-form-model]),ng-form,[ng-form]',
   hostInjector: [formDirectiveBinding],

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

@@ -13,7 +13,7 @@ const formControlBinding =
     CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgFormControl)}));
 
 /**
- * Binds a control to a DOM element.
+ * Binds an existing control to a DOM element.
  *
  * # Example
  *
@@ -23,9 +23,6 @@ const formControlBinding =
  * 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.
- *
  *  ```
  * @Component({selector: "login-comp"})
  * @View({
@@ -42,6 +39,24 @@ const formControlBinding =
  *
  *  ```
  *
+ * We can also use ng-model to bind a domain model to the form.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [formDirectives],
+ *      template: "<input type='text' [ng-form-control]='loginControl' [(ng-model)]='login'>"
+ *      })
+ * class LoginComp {
+ *  loginControl:Control;
+ *  login:string;
+ *
+ *  constructor() {
+ *    this.loginControl = new Control('');
+ *  }
+ * }
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Directive({

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

@@ -15,7 +15,7 @@ const formDirectiveBinding =
     CONST_EXPR(new Binding(ControlContainer, {toAlias: FORWARD_REF(() => NgFormModel)}));
 
 /**
- * Binds a control group to a DOM element.
+ * Binds an existing control group to a DOM element.
  *
  * # Example
  *
@@ -23,9 +23,6 @@ const formDirectiveBinding =
  * password controls to the
  * login and password elements.
  *
- * Here we use {@link formDirectives}, rather than importing each form directive individually, e.g.
- * `NgControl`, `NgControlGroup`. This is just a shorthand for the same end result.
- *
  *  ```
  * @Component({selector: "login-comp"})
  * @View({
@@ -53,6 +50,36 @@ const formDirectiveBinding =
  *
  *  ```
  *
+ * We can also use ng-model to bind a domain model to the form.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [formDirectives],
+ *      template: "<form [ng-form-model]='loginForm'>" +
+ *              "Login <input type='text' ng-control='login' [(ng-model)]='login'>" +
+ *              "Password <input type='password' ng-control='password' [(ng-model)]='password'>" +
+ *              "<button (click)="onLogin()">Login</button>" +
+ *              "</form>"
+ *      })
+ * class LoginComp {
+ *  credentials:{login:string, password:string}
+ *  loginForm:ControlGroup;
+ *
+ *  constructor() {
+ *    this.loginForm = new ControlGroup({
+ *      login: new Control(""),
+ *      password: new Control("")
+ *    });
+ *  }
+ *
+ *  onLogin() {
+ *    // this.credentials.login === 'some login'
+ *    // this.credentials.password === 'some password'
+ *  }
+ * }
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Directive({

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

@@ -12,6 +12,24 @@ import {setUpControl} from './shared';
 const formControlBinding =
     CONST_EXPR(new Binding(NgControl, {toAlias: FORWARD_REF(() => NgModel)}));
 
+/**
+ * Binds a domain model to the form.
+ *
+ * # Example
+ *  ```
+ * @Component({selector: "search-comp"})
+ * @View({
+ *      directives: [formDirectives],
+ *      template: `
+              <input type='text' [(ng-model)]="searchQuery">
+ *      `})
+ * class SearchComp {
+ *  searchQuery: string;
+ * }
+ *  ```
+ *
+ * @exportedAs angular2/forms
+ */
 @Directive({
   selector: '[ng-model]:not([ng-control]):not([ng-form-control])',
   hostInjector: [formControlBinding],

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

@@ -3,15 +3,7 @@ import {NgControl} from './ng_control';
 import {ControlValueAccessor} from './control_value_accessor';
 
 /**
- * The accessor for writing a value and listening to changes that is used by a
- * {@link Control} directive.
- *
- * This is the default strategy that Angular uses when no other accessor is applied.
- *
- *  # Example
- *  ```
- *  <input type="text" [ng-control]="loginControl">
- *  ```
+ * The accessor for writing a value and listening to changes on a select element.
  *
  * @exportedAs angular2/forms
  */