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

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(