cleanup(docs): Edited API docs

modules/angular2/src/forms/directives.js

@@ -11,6 +11,15 @@ import {Validators} from './validators';
 //}
 
 /**
+ * The default accessor for writing a value and listening to changes that is used by a [Control] directive.
+ *
+ * This is the default strategy that Angular uses when no other accessor is applied.
+ *
+ *  # Example
+ *  ```
+ *  <input type="text" [control]="loginControl">
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -35,6 +44,14 @@ export class DefaultValueAccessor {
 }
 
 /**
+ * The accessor for writing a value and listening to changes on a checkbox input element.
+ *
+ *
+ *  # Example
+ *  ```
+ *  <input type="checkbox" [control]="rememberLogin">
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -59,6 +76,33 @@ export class CheckboxControlValueAccessor {
 }
 
 /**
+ * Binds a control to a DOM element.
+ *
+ * # Example
+ *
+ * In this example, we bind the 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 [FormDirectives], rather than importing each form directive individually, e.g.
+ * `ControlDirective`, `ControlGroupDirective`. This is just a shorthand for the same end result.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [FormDirectives],
+ *      inline: "<input type='text' [control]='loginControl'>"
+ *      })
+ * class LoginComp {
+ *  loginControl:Control;
+ *
+ *  constructor() {
+ *    this.loginControl = new Control('');
+ *  }
+ * }
+ *
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -119,6 +163,43 @@ export class ControlDirective {
 }
 
 /**
+ * Binds a control group to a DOM element.
+ *
+ * # Example
+ *
+ * In this example, we bind the control group to the form element, and we bind the login and password controls to the
+ * login and password elements.
+ *
+ * Here we use [FormDirectives], rather than importing each form directive individually, e.g.
+ * `ControlDirective`, `ControlGroupDirective`. This is just a shorthand for the same end result.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [FormDirectives],
+ *      inline: "<form [control-group]='loginForm'>" +
+ *              "Login <input type='text' control='login'>" +
+ *              "Password <input type='password' control='password'>" +
+ *              "<button (click)="onLogin()">Login</button>" +
+ *              "</form>"
+ *      })
+ * class LoginComp {
+ *  loginForm:ControlGroup;
+ *
+ *  constructor() {
+ *    this.loginForm = new ControlGroup({
+ *      login: new Control(""),
+ *      password: new Control("")
+ *    });
+ *  }
+ *
+ *  onLogin() {
+ *    // this.loginForm.value
+ *  }
+ * }
+ *
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -170,6 +251,11 @@ export class ControlGroupDirective {
 }
 
 /**
+ *
+ * A list of all the form directives used as part of a `@View` annotation.
+ *
+ *  This is a shorthand for importing them each individually.
+ *
  * @exportedAs angular2/forms
  */
 // todo(misko): rename to lover case as it is not a Type but a var.

modules/angular2/src/forms/form_builder.js

@@ -4,6 +4,24 @@ import * as modelModule from './model';
 
 
 /**
+ * Creates a form object from a user-specified configuration.
+ *
+ * # Example
+ *
+ * This example creates a [ControlGroup] that consists of a `login` [Control], and a nested [ControlGroup] that defines
+ * a `password` and a `passwordConfirmation` [Control].
+ *
+ * ```
+ *  var loginForm = builder.group({
+ *    login: ["", Validators.required],
+ *
+ *    passwordRetry: builder.group({
+ *      password: ["", Validators.required],
+ *      passwordConfirmation: ["", Validators.required]
+ *    })
+ *  });
+ *
+ *  ```
  * @exportedAs angular2/forms
  */
 export class FormBuilder {
@@ -59,4 +77,4 @@ export class FormBuilder {
       return this.control(controlConfig);
     }
   }
-}
+}

modules/angular2/src/forms/model.js

@@ -4,11 +4,15 @@ import {StringMap, StringMapWrapper, ListWrapper, List} from 'angular2/src/facad
 import {Validators} from './validators';
 
 /**
+ * Indicates that a Control is valid, i.e. that no errors exist in the input value.
+ *
  * @exportedAs angular2/forms
  */
 export const VALID = "VALID";
 
 /**
+ * Indicates that a Control is invalid, i.e. that an error exists in the input value.
+ *
  * @exportedAs angular2/forms
  */
 export const INVALID = "INVALID";
@@ -26,7 +30,7 @@ export const INVALID = "INVALID";
 //}
 
 /**
- * @exportedAs angular2/forms
+ * Omitting from external API doc as this is really an abstract internal concept.
  */
 export class AbstractControl {
   _value:any;
@@ -80,6 +84,11 @@ export class AbstractControl {
 }
 
 /**
+ * Defines a part of a form that cannot be divided into other controls.
+ *
+ * `Control` is one of the three fundamental building blocks used to define forms in Angular, along with [ControlGroup]
+ * and [ControlArray].
+ *
  * @exportedAs angular2/forms
  */
 export class Control extends AbstractControl {
@@ -108,6 +117,15 @@ export class Control extends AbstractControl {
 }
 
 /**
+ * Defines a part of a form, of fixed length, that can contain other controls.
+ *
+ * A ControlGroup aggregates the values and errors of each [Control] in the group. Thus, if one of the controls in a
+ * group is invalid, the entire group is invalid. Similarly, if a control changes its value, the entire group changes
+ * as well.
+ *
+ * `ControlGroup` is one of the three fundamental building blocks used to define forms in Angular, along with [Control]
+ * and [ControlArray]. [ControlArray] can also contain other controls, but is of variable length.
+ *
  * @exportedAs angular2/forms
  */
 export class ControlGroup extends AbstractControl {
@@ -186,6 +204,15 @@ export class ControlGroup extends AbstractControl {
 }
 
 /**
+ * Defines a part of a form, of variable length, that can contain other controls.
+ *
+ * A `ControlArray` aggregates the values and errors of each [Control] in the group. Thus, if one of the controls in a
+ * group is invalid, the entire group is invalid. Similarly, if a control changes its value, the entire group changes
+ * as well.
+ *
+ * `ControlArray` is one of the three fundamental building blocks used to define forms in Angular, along with [Control]
+ * and [ControlGroup]. [ControlGroup] can also contain other controls, but is of fixed length.
+ *
  * @exportedAs angular2/forms
  */
 export class ControlArray extends AbstractControl {

modules/angular2/src/forms/validators.js

@@ -4,6 +4,14 @@ import {List, ListWrapper, StringMapWrapper} from 'angular2/src/facade/collectio
 import * as modelModule from './model';
 
 /**
+ * Provides a set of validators used by form controls.
+ *
+ * # Example
+ *
+ * ```
+ * var loginControl = new Control("", Validators.required)
+ * ```
+ *
  * @exportedAs angular2/forms
  */
 export class Validators {