docs(forms): update docs for FormBuilder (#11548)

modules/@angular/examples/forms/ts/formBuilder/e2e_test/form_builder_spec.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+
+describe('formBuilder example', () => {
+  afterEach(verifyNoBrowserErrors);
+  let inputs: ElementFinder;
+  let paragraphs: ElementFinder;
+
+  beforeEach(() => {
+    browser.get('/forms/ts/formBuilder/index.html');
+    inputs = element.all(by.css('input'));
+    paragraphs = element.all(by.css('p'));
+  });
+
+  it('should populate the UI with initial values', () => {
+    expect(inputs.get(0).getAttribute('value')).toEqual('Nancy');
+    expect(inputs.get(1).getAttribute('value')).toEqual('Drew');
+  });
+
+  it('should update the validation status', () => {
+    expect(paragraphs.get(1).getText()).toEqual('Validation status: VALID');
+
+    inputs.get(0).click();
+    inputs.get(0).clear();
+    inputs.get(0).sendKeys('a');
+    expect(paragraphs.get(1).getText()).toEqual('Validation status: INVALID');
+  });
+
+});

modules/@angular/examples/forms/ts/formBuilder/form_builder_example.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// #docregion Component
+import {Component, Inject} from '@angular/core';
+import {FormBuilder, FormGroup, Validators} from '@angular/forms';
+
+@Component({
+  selector: 'example-app',
+  template: `
+    <form [formGroup]="form">
+      <div formGroupName="name">
+        <input formControlName="first" placeholder="First">
+        <input formControlName="last" placeholder="Last">
+      </div>
+      <input formControlName="email" placeholder="Email">
+      <button>Submit</button>
+    </form>
+    
+    <p>Value: {{ form.value | json }}</p>
+    <p>Validation status: {{ form.status }}</p>
+  `
+})
+export class FormBuilderComp {
+  form: FormGroup;
+
+  constructor(@Inject(FormBuilder) fb: FormBuilder) {
+    this.form = fb.group({
+      name: fb.group({
+        first: ['Nancy', Validators.minLength(2)],
+        last: 'Drew',
+      }),
+      email: '',
+    });
+  }
+}
+// #enddocregion

modules/@angular/examples/forms/ts/formBuilder/module.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {NgModule} from '@angular/core';
+import {ReactiveFormsModule} from '@angular/forms';
+import {BrowserModule} from '@angular/platform-browser';
+import {FormBuilderComp} from './form_builder_example';
+
+@NgModule({
+  imports: [BrowserModule, ReactiveFormsModule],
+  declarations: [FormBuilderComp],
+  bootstrap: [FormBuilderComp]
+})
+export class AppModule {
+}

modules/@angular/forms/src/form_builder.ts

@@ -13,45 +13,23 @@ import {StringMapWrapper} from './facade/collection';
 import {isArray, isPresent} from './facade/lang';
 import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
 
-
-
 /**
- * Creates a form object from a user-specified configuration.
+ * @whatItDoes Creates an {@link AbstractControl} from a user-specified configuration.
  *
- * ```typescript
- * @Component({
- *   selector: 'my-app',
- *   template: `
- *     <form [formGroup]="loginForm">
- *       <p>Login <input formControlName="login"></p>
- *       <div formGroupName="passwordRetry">
- *         <p>Password <input type="password" formControlName="password"></p>
- *         <p>Confirm password <input type="password" formControlName="passwordConfirmation"></p>
- *       </div>
- *     </form>
- *     <h3>Form value:</h3>
- *     <pre>{{value}}</pre>
- *   `,
- *   directives: [REACTIVE_FORM_DIRECTIVES]
- * })
- * export class App {
- *   loginForm: FormGroup;
+ * It is essentially syntactic sugar that shortens the `new FormGroup()`,
+ * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
+ * forms.
  *
- *   constructor(builder: FormBuilder) {
- *     this.loginForm = builder.group({
- *       login: ["", Validators.required],
- *       passwordRetry: builder.group({
- *         password: ["", Validators.required],
- *         passwordConfirmation: ["", Validators.required, asyncValidator]
- *       })
- *     });
- *   }
+ * @howToUse
  *
- *   get value(): string {
- *     return JSON.stringify(this.loginForm.value, null, 2);
- *   }
- * }
- * ```
+ * To use, inject `FormBuilder` into your component class. You can then call its methods
+ * directly.
+ *
+ * {@example forms/ts/formBuilder/form_builder_example.ts region='Component'}
+ *
+ *  * **npm package**: `@angular/forms`
+ *
+ *  * **NgModule**: {@link ReactiveFormsModule}
  *
  * @stable
  */
@@ -59,7 +37,7 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
 export class FormBuilder {
   /**
    * Construct a new {@link FormGroup} with the given map of configuration.
-   * Valid keys for the `extra` parameter map are `optionals` and `validator`.
+   * Valid keys for the `extra` parameter map are `validator` and `asyncValidator`.
    *
    * See the {@link FormGroup} constructor for more details.
    */
@@ -74,6 +52,10 @@ export class FormBuilder {
   /**
    * Construct a new {@link FormControl} with the given `formState`,`validator`, and
    * `asyncValidator`.
+   *
+   * `formState` can either be a standalone value for the form control or an object
+   * that contains both a value and a disabled status.
+   *
    */
   control(
       formState: Object, validator: ValidatorFn|ValidatorFn[] = null,
@@ -82,7 +64,7 @@ export class FormBuilder {
   }
 
   /**
-   * Construct an array of {@link FormControl}s from the given `controlsConfig` array of
+   * Construct a {@link FormArray} from the given `controlsConfig` array of
    * configuration, with the given optional `validator` and `asyncValidator`.
    */
   array(