diff --git a/packages/examples/forms/ts/formBuilder/form_builder_example.ts b/packages/examples/forms/ts/formBuilder/form_builder_example.ts
index 01a9690977..e6fbd9c3eb 100644
--- a/packages/examples/forms/ts/formBuilder/form_builder_example.ts
+++ b/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: `
+
+ `
+})
+export class DisabledFormControlComponent {
+ control: FormControl;
+
+ constructor(private fb: FormBuilder) {
+ this.control = fb.control({value: 'my val', disabled: true});
+ }
+}
+// #enddocregion disabled-control
\ No newline at end of file
diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts
index ccb1fd9563..9b3c4570ec 100644
--- a/packages/forms/src/form_builder.ts
+++ b/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()`,
- * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger
+ * The `FormBuilder` provides syntactic sugar that shortens creating instances of a `FormControl`,
+ * `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
- * directly.
- *
- * {@example forms/ts/formBuilder/form_builder_example.ts region='Component'}
- *
- * * **npm package**: `@angular/forms`
- *
- * * **NgModule**: `ReactiveFormsModule`
- *
+ * @see [Reactive Forms Guide](/guide/reactive-forms)
*
*/
@Injectable()
export class FormBuilder {
/**
- * Construct a new `FormGroup` with the given map of configuration.
- * Valid keys for the `extra` parameter map are `validator` and `asyncValidator`.
+ * @description
+ * 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
- * `asyncValidator`.
+ * @description
+ * Construct a new `FormControl` instance.
*
- * `formState` can either be a standalone value for the form control or an object
- * that contains both a value and a disabled status.
+ * @param formState Initializes the control with an initial value,
+ * 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.
+ *
+ *
+ *
*
*/
control(
@@ -60,8 +73,16 @@ export class FormBuilder {
}
/**
- * Construct a `FormArray` from the given `controlsConfig` array of
- * configuration, with the given optional `validator` and `asyncValidator`.
+ * @description
+ * 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,
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
index c0edddc4c9..05c0a2b057 100644
--- a/packages/forms/src/model.ts
+++ b/packages/forms/src/model.ts
@@ -872,9 +872,8 @@ export class FormControl extends AbstractControl {
/**
* Creates a new `FormControl` instance.
*
- * @param formState Initializes the control with an initial state value,
- * or with an object that defines the initial value, status, and options
- * for handling updates and validation.
+ * @param formState Initializes the control with an initial value,
+ * or an object that defines the initial value and disabled state.
*
* @param validatorOrOpts A synchronous validator function, or an array of
* such functions, or an `AbstractControlOptions` object that contains validation functions
@@ -955,9 +954,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,
- * or with an object that defines the initial value, status, and options
- * for handling updates and validation.
+ * @param formState Resets the control with an initial value,
+ * or an object that defines the initial value and disabled state.
*
* @param options Configuration options that determine how the control propagates changes
* and emits events after the value changes.
@@ -1311,9 +1309,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,
- * or with an object that defines the initial value, status,
- * and options for handling updates and validation.
+ * @param formState Resets the control with an initial value,
+ * or an object that defines the initial value and disabled state.
*
* @param options Configuration options that determine how the control propagates changes
* and emits events when the group is reset.