docs(forms): update form builder API reference (#24693)

PR Close #24693

packages/examples/forms/ts/formBuilder/form_builder_example.ts

@@ -6,9 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-// #docregion Component
+// #docregion Component, disabled-control
 import {Component, Inject} from '@angular/core';
-import {FormBuilder, FormGroup, Validators} from '@angular/forms';
+import {FormBuilder, FormControl, FormGroup, Validators} from '@angular/forms';
+// #enddocregion disabled-control
 
 @Component({
   selector: 'example-app',
@@ -40,3 +41,19 @@ export class FormBuilderComp {
   }
 }
 // #enddocregion
+
+// #docregion disabled-control
+@Component({
+  selector: 'app-disabled-form-control',
+  template: `
+    <input [formControl]="control" placeholder="First">
+  `
+})
+export class DisabledFormControlComponent {
+  control: FormControl;
+
+  constructor(private fb: FormBuilder) {
+    this.control = fb.control({value: 'my val', disabled: true});
+  }
+}
+// #enddocregion disabled-control

packages/forms/src/form_builder.ts

@@ -13,31 +13,28 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
 
 /**
  * @description
- *
  * Creates an `AbstractControl` from a user-specified configuration.
  *
- * This is essentially syntactic sugar that shortens the `new FormGroup()`,
+ * The `FormBuilder` provides syntactic sugar that shortens creating instances of a `FormControl`,
- * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
+ * `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to build complex
  * forms.
  *
- * To use, inject `FormBuilder` into your component class. You can then call its methods
+ * @see [Reactive Forms Guide](/guide/reactive-forms)
- * directly.
- *
- * {@example forms/ts/formBuilder/form_builder_example.ts region='Component'}
- *
- *  * **npm package**: `@angular/forms`
- *
- *  * **NgModule**: `ReactiveFormsModule`
- *
  *
  */
 @Injectable()
 export class FormBuilder {
   /**
-   * Construct a new `FormGroup` with the given map of configuration.
+   * @description
-   * Valid keys for the `extra` parameter map are `validator` and `asyncValidator`.
+   * Construct a new `FormGroup` instance.
+   *
+   * @param controlsConfig A collection of child controls. The key for each child is the name
+   * under which it is registered.
+   *
+   * @param extra An object of configuration options for the `FormGroup`.
+   * * `validator`: A synchronous validator function, or an array of validator functions
+   * * `asyncValidator`: A single async validator or array of async validator functions
    *
-   * See the `FormGroup` constructor for more details.
    */
   group(controlsConfig: {[key: string]: any}, extra: {[key: string]: any}|null = null): FormGroup {
     const controls = this._reduceControls(controlsConfig);
@@ -45,12 +42,28 @@ export class FormBuilder {
     const asyncValidator: AsyncValidatorFn = extra != null ? extra['asyncValidator'] : null;
     return new FormGroup(controls, validator, asyncValidator);
   }
+
   /**
-   * Construct a new `FormControl` with the given `formState`,`validator`, and
+   * @description
-   * `asyncValidator`.
+   * Construct a new `FormControl` instance.
    *
-   * `formState` can either be a standalone value for the form control or an object
+   * @param formState Initializes the control with an initial value,
-   * that contains both a value and a disabled status.
+   * or an object that defines the initial value and disabled state.
+   *
+   * @param validator A synchronous validator function, or an array of synchronous validator
+   * functions.
+   *
+   * @param asyncValidator A single async validator or array of async validator functions
+   *
+   * @usageNotes
+   *
+   * ### Initialize a control as disabled
+   *
+   * The following example returns a control with an initial value in a disabled state.
+   *
+   * <code-example path="forms/ts/formBuilder/form_builder_example.ts"
+   *   linenums="false" region="disabled-control">
+   * </code-example>
    *
    */
   control(
@@ -60,8 +73,16 @@ export class FormBuilder {
   }
 
   /**
-   * Construct a `FormArray` from the given `controlsConfig` array of
+   * @description
-   * configuration, with the given optional `validator` and `asyncValidator`.
+   * Construct a new `FormArray` instance.
+   *
+   * @param controlsConfig An array of child controls. The key for each child control is its index
+   * in the array.
+   *
+   * @param validator A synchronous validator function, or an array of synchronous validator
+   * functions.
+   *
+   * @param asyncValidator A single async validator or array of async validator functions
    */
   array(
       controlsConfig: any[], validator?: ValidatorFn|ValidatorFn[]|null,

packages/forms/src/model.ts

@@ -880,9 +880,8 @@ export class FormControl extends AbstractControl {
   /**
   * Creates a new `FormControl` instance.
   *
-  * @param formState Initializes the control with an initial state value,
+  * @param formState Initializes the control with an initial value,
-  * or with an object that defines the initial value, status, and options
+  * or an object that defines the initial value and disabled state.
-  * for handling updates and validation.
   *
   * @param validatorOrOpts A synchronous validator function, or an array of
   * such functions, or an `AbstractControlOptions` object that contains validation functions
@@ -963,9 +962,8 @@ export class FormControl extends AbstractControl {
    * Resets the form control, marking it `pristine` and `untouched`, and setting
    * the value to null.
    *
-   * @param formState Initializes the control with an initial state value,
+   * @param formState Resets the control with an initial value,
-   * or with an object that defines the initial value, status, and options
+   * or an object that defines the initial value and disabled state.
-   * for handling updates and validation.
    *
    * @param options Configuration options that determine how the control propagates changes
    * and emits events after the value changes.
@@ -1319,9 +1317,8 @@ export class FormGroup extends AbstractControl {
    * is a standalone value or a form state object with both a value and a disabled
    * status.
    *
-   * @param value Initializes the control with an initial state value,
+   * @param formState Resets the control with an initial value,
-   * or with an object that defines the initial value, status,
+   * or an object that defines the initial value and disabled state.
-   * and options for handling updates and validation.
    *
    * @param options Configuration options that determine how the control propagates changes
    * and emits events when the group is reset.