honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(forms): remove unnecessary `{@link Injector}` jsdoc tags (#23186) 

Inline code blocks are automatically linked, if possible, to their API
page.

PR Close #23186
This commit is contained in:
Pete Bacon Darwin 2018-04-05 10:58:12 +01:00 committed by Igor Minar
parent 1aef4df127
commit 92821e338b
23 changed files with 136 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
packages/forms/src/directives/abstract_control_directive.ts
View File

@ -19,7 +19,7 @@ import {ValidationErrors} from './validators';
*/
export abstract class AbstractControlDirective {
/**
* The {@link FormControl}, {@link FormGroup}, or {@link FormArray}
* The `FormControl`, `FormGroup`, or `FormArray`
* that backs this directive. Most properties fall through to that
* instance.
*/
@ -137,7 +137,7 @@ export abstract class AbstractControlDirective {
* * it is marked as `untouched`
* * value is set to null
*
* For more information, see {@link AbstractControl}.
* For more information, see `AbstractControl`.
*/
reset(value: any = undefined): void {
if (this.control) this.control.reset(value);

6
packages/forms/src/directives/abstract_form_group_directive.ts
View File

@ -18,7 +18,7 @@ import {AsyncValidatorFn, ValidatorFn} from './validators';
/**
* This is a base class for code shared between {@link NgModelGroup} and {@link FormGroupName}.
* This is a base class for code shared between `NgModelGroup` and `FormGroupName`.
*
* @stable
*/
@ -44,7 +44,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
}
/**
* Get the {@link FormGroup} backing this binding.
* Get the `FormGroup` backing this binding.
*/
get control(): FormGroup { return this.formDirective !.getFormGroup(this); }
@ -54,7 +54,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
get path(): string[] { return controlPath(this.name, this._parent); }
/**
* Get the {@link Form} to which this group belongs.
* Get the `Form` to which this group belongs.
*/
get formDirective(): Form|null { return this._parent ? this._parent.formDirective : null; }

2
packages/forms/src/directives/control_container.ts
View File

@ -11,7 +11,7 @@ import {Form} from './form_interface';
/**
* A directive that contains multiple {@link NgControl}s.
* A directive that contains multiple `NgControl`s.
*
* Only used by the forms module.
*

4
packages/forms/src/directives/control_value_accessor.ts
View File

@ -110,9 +110,9 @@ export interface ControlValueAccessor {
}
/**
* Used to provide a {@link ControlValueAccessor} for form controls.
* Used to provide a `ControlValueAccessor` for form controls.
*
* See {@link DefaultValueAccessor} for how to implement one.
* See `DefaultValueAccessor` for how to implement one.
* @stable
*/
export const NG_VALUE_ACCESSOR = new InjectionToken<ControlValueAccessor>('NgValueAccessor');

2
packages/forms/src/directives/default_value_accessor.ts
View File

@ -33,7 +33,7 @@ export const COMPOSITION_BUFFER_MODE = new InjectionToken<boolean>('CompositionE
/**
* The default accessor for writing a value and listening to changes that is used by the
* {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```

6
packages/forms/src/directives/form_interface.ts
View File

@ -14,7 +14,7 @@ import {NgControl} from './ng_control';
/**
* An interface that {@link FormGroupDirective} and {@link NgForm} implement.
* An interface that `FormGroupDirective` and `NgForm` implement.
*
* Only used by the forms module.
*
@ -32,7 +32,7 @@ export interface Form {
removeControl(dir: NgControl): void;
/**
* Look up the {@link FormControl} associated with a particular {@link NgControl}.
* Look up the `FormControl` associated with a particular `NgControl`.
*/
getControl(dir: NgControl): FormControl;
@ -47,7 +47,7 @@ export interface Form {
removeFormGroup(dir: AbstractFormGroupDirective): void;
/**
* Look up the {@link FormGroup} associated with a particular {@link AbstractFormGroupDirective}.
* Look up the `FormGroup` associated with a particular `AbstractFormGroupDirective`.
*/
getFormGroup(dir: AbstractFormGroupDirective): FormGroup;

2
packages/forms/src/directives/ng_control.ts
View File

@ -18,7 +18,7 @@ function unimplemented(): any {
/**
* A base class that all control directive extend.
* It binds a {@link FormControl} object to a DOM element.
* It binds a `FormControl` object to a DOM element.
*
* Used internally by Angular forms.
*

8
packages/forms/src/directives/ng_form.ts
View File

@ -28,7 +28,7 @@ const resolvedPromise = Promise.resolve(null);
/**
* @description
*
* Creates a top-level {@link FormGroup} instance and binds it to a form
* Creates a top-level `FormGroup` instance and binds it to a form
* to track aggregate form value and validation status.
*
* As soon as you import the `FormsModule`, this directive becomes active by default on
@ -36,12 +36,12 @@ const resolvedPromise = Promise.resolve(null);
*
* You can export the directive into a local template variable using `ngForm` as the key
* (ex: `#myForm="ngForm"`). This is optional, but useful. Many properties from the underlying
* {@link FormGroup} instance are duplicated on the directive itself, so a reference to it
* `FormGroup` instance are duplicated on the directive itself, so a reference to it
* will give you access to the aggregate value and validity status of the form, as well as
* user interaction properties like `dirty` and `touched`.
*
* To register child controls with the form, you'll want to use {@link NgModel} with a
* `name` attribute. You can also use {@link NgModelGroup} if you'd like to create
* To register child controls with the form, you'll want to use `NgModel` with a
* `name` attribute. You can also use `NgModelGroup` if you'd like to create
* sub-groups within the form.
*
* You can listen to the directive's `ngSubmit` event to be notified when the user has

14
packages/forms/src/directives/ng_model.ts
View File

@ -48,10 +48,10 @@ const resolvedPromise = Promise.resolve(null);
/**
* @description
*
* Creates a {@link FormControl} instance from a domain model and binds it
* Creates a `FormControl` instance from a domain model and binds it
* to a form control element.
*
* The {@link FormControl} instance will track the value, user interaction, and
* The `FormControl` instance will track the value, user interaction, and
* validation status of the control and keep the view synced with the model. If used
* within a parent form, the directive will also register itself with the form as a child
* control.
@ -59,18 +59,18 @@ const resolvedPromise = Promise.resolve(null);
* This directive can be used by itself or as part of a larger form. All you need is the
* `ngModel` selector to activate it.
*
* It accepts a domain model as an optional {@link Input}. If you have a one-way binding
* It accepts a domain model as an optional `Input`. If you have a one-way binding
* to `ngModel` with `[]` syntax, changing the value of the domain model in the component
* class will set the value in the view. If you have a two-way binding with `[()]` syntax
* (also known as 'banana-box syntax'), the value in the UI will always be synced back to
* the domain model in your class as well.
*
* If you wish to inspect the properties of the associated {@link FormControl} (like
* If you wish to inspect the properties of the associated `FormControl` (like
* validity state), you can also export the directive into a local template variable using
* `ngModel` as the key (ex: `#myVar="ngModel"`). You can then access the control using the
* directive's `control` property, but most properties you'll need (like `valid` and `dirty`)
* will fall through to the control anyway, so you can access them directly. You can see a
* full list of properties directly available in {@link AbstractControlDirective}.
* full list of properties directly available in `AbstractControlDirective`.
*
* The following is an example of a simple standalone control using `ngModel`:
*
@ -94,8 +94,8 @@ const resolvedPromise = Promise.resolve(null);
*
* To see `ngModel` examples with different form control types, see:
*
* * Radio buttons: {@link RadioControlValueAccessor}
* * Selects: {@link SelectControlValueAccessor}
* * Radio buttons: `RadioControlValueAccessor`
* * Selects: `SelectControlValueAccessor`
*
* **npm package**: `@angular/forms`
*

4
packages/forms/src/directives/ng_model_group.ts
View File

@ -23,9 +23,9 @@ export const modelGroupProvider: any = {
/**
* @description
*
* Creates and binds a {@link FormGroup} instance to a DOM element.
* Creates and binds a `FormGroup` instance to a DOM element.
*
* This directive can only be used as a child of {@link NgForm} (or in other words,
* This directive can only be used as a child of `NgForm` (or in other words,
* within `<form>` tags).
*
* Use this directive if you'd like to create a sub-group within a form. This can

2
packages/forms/src/directives/number_value_accessor.ts
View File

@ -18,7 +18,7 @@ export const NUMBER_VALUE_ACCESSOR: any = {
/**
* The accessor for writing a number value and listening to changes that is used by the
* {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```

6
packages/forms/src/directives/radio_control_value_accessor.ts
View File

@ -59,10 +59,10 @@ export class RadioControlRegistry {
*
* Writes radio control values and listens to radio control changes.
*
* Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
* to keep the view synced with the {@link FormControl} model.
* Used by `NgModel`, `FormControlDirective`, and `FormControlName`
* to keep the view synced with the `FormControl` model.
*
* If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
* If you have imported the `FormsModule` or the `ReactiveFormsModule`, this
* value accessor will be active on any radio control that has a form directive. You do
* **not** need to add a special selector to activate it.
*

2
packages/forms/src/directives/range_value_accessor.ts
View File

@ -18,7 +18,7 @@ export const RANGE_VALUE_ACCESSOR: StaticProvider = {
/**
* The accessor for writing a range value and listening to changes that is used by the
* {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```

24
packages/forms/src/directives/reactive_directives/form_control_directive.ts
View File

@ -31,27 +31,27 @@ export const formControlBinding: any = {
/**
* @description
*
* Syncs a standalone {@link FormControl} instance to a form control element.
* Syncs a standalone `FormControl` instance to a form control element.
*
* This directive ensures that any values written to the {@link FormControl}
* This directive ensures that any values written to the `FormControl`
* instance programmatically will be written to the DOM element (model -> view). Conversely,
* any values written to the DOM element through user input will be reflected in the
* {@link FormControl} instance (view -> model).
* `FormControl` instance (view -> model).
*
* Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
* Simply create a {@link FormControl}, save it to your component class, and pass it into the
* {@link FormControlDirective}.
* Use this directive if you'd like to create and manage a `FormControl` instance directly.
* Simply create a `FormControl`, save it to your component class, and pass it into the
* `FormControlDirective`.
*
* This directive is designed to be used as a standalone control. Unlike {@link FormControlName},
* it does not require that your {@link FormControl} instance be part of any parent
* {@link FormGroup}, and it won't be registered to any {@link FormGroupDirective} that
* This directive is designed to be used as a standalone control. Unlike `FormControlName`,
* it does not require that your `FormControl` instance be part of any parent
* `FormGroup`, and it won't be registered to any `FormGroupDirective` that
* exists above it.
*
* **Get the value**: the `value` property is always synced and available on the
* {@link FormControl} instance. See a full list of available properties in
* {@link AbstractControl}.
* `FormControl` instance. See a full list of available properties in
* `AbstractControl`.
*
* **Set the value**: You can pass in an initial value when instantiating the {@link FormControl},
* **Set the value**: You can pass in an initial value when instantiating the `FormControl`,
* or you can set it programmatically later using {@link AbstractControl#setValue setValue} or
* {@link AbstractControl#patchValue patchValue}.
*

28
packages/forms/src/directives/reactive_directives/form_control_name.ts
View File

@ -30,30 +30,30 @@ export const controlNameBinding: any = {
/**
* @description
*
* Syncs a {@link FormControl} in an existing {@link FormGroup} to a form control
* Syncs a `FormControl` in an existing `FormGroup` to a form control
* element by name.
*
* This directive ensures that any values written to the {@link FormControl}
* This directive ensures that any values written to the `FormControl`
* instance programmatically will be written to the DOM element (model -> view). Conversely,
* any values written to the DOM element through user input will be reflected in the
* {@link FormControl} instance (view -> model).
* `FormControl` instance (view -> model).
*
* This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
* This directive is designed to be used with a parent `FormGroupDirective` (selector:
* `[formGroup]`).
*
* It accepts the string name of the {@link FormControl} instance you want to
* link, and will look for a {@link FormControl} registered with that name in the
* closest {@link FormGroup} or {@link FormArray} above it.
* It accepts the string name of the `FormControl` instance you want to
* link, and will look for a `FormControl` registered with that name in the
* closest `FormGroup` or `FormArray` above it.
*
* **Access the control**: You can access the {@link FormControl} associated with
* **Access the control**: You can access the `FormControl` associated with
* this directive by using the {@link AbstractControl#get get} method.
* Ex: `this.form.get('first');`
*
* **Get value**: the `value` property is always synced and available on the {@link FormControl}.
* See a full list of available properties in {@link AbstractControl}.
* **Get value**: the `value` property is always synced and available on the `FormControl`.
* See a full list of available properties in `AbstractControl`.
*
* **Set value**: You can set an initial value for the control when instantiating the
* {@link FormControl}, or you can set it programmatically later using
* `FormControl`, or you can set it programmatically later using
* {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}.
*
* **Listen to value**: If you want to listen to changes in the value of the control, you can
@ -69,12 +69,12 @@ export const controlNameBinding: any = {
*
* To see `formControlName` examples with different form control types, see:
*
* * Radio buttons: {@link RadioControlValueAccessor}
* * Selects: {@link SelectControlValueAccessor}
* * Radio buttons: `RadioControlValueAccessor`
* * Selects: `SelectControlValueAccessor`
*
* **npm package**: `@angular/forms`
*
* **NgModule**: {@link ReactiveFormsModule}
* **NgModule**: `ReactiveFormsModule`
*
* ### Use with ngModel
*

16
packages/forms/src/directives/reactive_directives/form_group_directive.ts
View File

@ -25,20 +25,20 @@ export const formDirectiveProvider: any = {
/**
* @description
*
* Binds an existing {@link FormGroup} to a DOM element.
* Binds an existing `FormGroup` to a DOM element.
*
* This directive accepts an existing {@link FormGroup} instance. It will then use this
* {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup},
* and {@link FormArray} instances to child {@link FormControlName}, {@link FormGroupName},
* and {@link FormArrayName} directives.
* This directive accepts an existing `FormGroup` instance. It will then use this
* `FormGroup` instance to match any child `FormControl`, `FormGroup`,
* and `FormArray` instances to child `FormControlName`, `FormGroupName`,
* and `FormArrayName` directives.
*
* **Set value**: You can set the form's initial value when instantiating the
* {@link FormGroup}, or you can set it programmatically later using the {@link FormGroup}'s
* `FormGroup`, or you can set it programmatically later using the `FormGroup`'s
* {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}
* methods.
*
* **Listen to value**: If you want to listen to changes in the value of the form, you can subscribe
* to the {@link FormGroup}'s {@link AbstractControl#valueChanges valueChanges} event. You can also
* to the `FormGroup`'s {@link AbstractControl#valueChanges valueChanges} event. You can also
* listen to its {@link AbstractControl#statusChanges statusChanges} event to be notified when the
* validation status is re-calculated.
*
@ -54,7 +54,7 @@ export const formDirectiveProvider: any = {
*
* **npm package**: `@angular/forms`
*
* **NgModule**: {@link ReactiveFormsModule}
* **NgModule**: `ReactiveFormsModule`
*
* @stable
*/

40
packages/forms/src/directives/reactive_directives/form_group_name.ts
View File

@ -26,30 +26,30 @@ export const formGroupNameProvider: any = {
/**
* @description
*
* Syncs a nested {@link FormGroup} to a DOM element.
* Syncs a nested `FormGroup` to a DOM element.
*
* This directive can only be used with a parent {@link FormGroupDirective} (selector:
* This directive can only be used with a parent `FormGroupDirective` (selector:
* `[formGroup]`).
*
* It accepts the string name of the nested {@link FormGroup} you want to link, and
* will look for a {@link FormGroup} registered with that name in the parent
* {@link FormGroup} instance you passed into {@link FormGroupDirective}.
* It accepts the string name of the nested `FormGroup` you want to link, and
* will look for a `FormGroup` registered with that name in the parent
* `FormGroup` instance you passed into `FormGroupDirective`.
*
* Nested form groups can come in handy when you want to validate a sub-group of a
* form separately from the rest or when you'd like to group the values of certain
* controls into their own nested object.
*
* **Access the group**: You can access the associated {@link FormGroup} using the
* **Access the group**: You can access the associated `FormGroup` using the
* {@link AbstractControl#get get} method. Ex: `this.form.get('name')`.
*
* You can also access individual controls within the group using dot syntax.
* Ex: `this.form.get('name.first')`
*
* **Get the value**: the `value` property is always synced and available on the
* {@link FormGroup}. See a full list of available properties in {@link AbstractControl}.
* `FormGroup`. See a full list of available properties in `AbstractControl`.
*
* **Set the value**: You can set an initial value for each child control when instantiating
* the {@link FormGroup}, or you can set it programmatically later using
* the `FormGroup`, or you can set it programmatically later using
* {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}.
*
* **Listen to value**: If you want to listen to changes in the value of the group, you can
@ -97,37 +97,37 @@ export const formArrayNameProvider: any = {
/**
* @description
*
* Syncs a nested {@link FormArray} to a DOM element.
* Syncs a nested `FormArray` to a DOM element.
*
* This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
* This directive is designed to be used with a parent `FormGroupDirective` (selector:
* `[formGroup]`).
*
* It accepts the string name of the nested {@link FormArray} you want to link, and
* will look for a {@link FormArray} registered with that name in the parent
* {@link FormGroup} instance you passed into {@link FormGroupDirective}.
* It accepts the string name of the nested `FormArray` you want to link, and
* will look for a `FormArray` registered with that name in the parent
* `FormGroup` instance you passed into `FormGroupDirective`.
*
* Nested form arrays can come in handy when you have a group of form controls but
* you're not sure how many there will be. Form arrays allow you to create new
* form controls dynamically.
*
* **Access the array**: You can access the associated {@link FormArray} using the
* {@link AbstractControl#get get} method on the parent {@link FormGroup}.
* **Access the array**: You can access the associated `FormArray` using the
* {@link AbstractControl#get get} method on the parent `FormGroup`.
* Ex: `this.form.get('cities')`.
*
* **Get the value**: the `value` property is always synced and available on the
* {@link FormArray}. See a full list of available properties in {@link AbstractControl}.
* `FormArray`. See a full list of available properties in `AbstractControl`.
*
* **Set the value**: You can set an initial value for each child control when instantiating
* the {@link FormArray}, or you can set the value programmatically later using the
* {@link FormArray}'s {@link AbstractControl#setValue setValue} or
* the `FormArray`, or you can set the value programmatically later using the
* `FormArray`'s {@link AbstractControl#setValue setValue} or
* {@link AbstractControl#patchValue patchValue} methods.
*
* **Listen to value**: If you want to listen to changes in the value of the array, you can
* subscribe to the {@link FormArray}'s {@link AbstractControl#valueChanges valueChanges} event.
* subscribe to the `FormArray`'s {@link AbstractControl#valueChanges valueChanges} event.
* You can also listen to its {@link AbstractControl#statusChanges statusChanges} event to be
* notified when the validation status is re-calculated.
*
* **Add new controls**: You can add new controls to the {@link FormArray} dynamically by calling
* **Add new controls**: You can add new controls to the `FormArray` dynamically by calling
* its {@link FormArray#push push} method.
* Ex: `this.form.get('cities').push(new FormControl());`
*

8
packages/forms/src/directives/select_control_value_accessor.ts
View File

@ -31,10 +31,10 @@ function _extractId(valueString: string): string {
*
* Writes values and listens to changes on a select element.
*
* Used by {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName}
* to keep the view synced with the {@link FormControl} model.
* Used by `NgModel`, `FormControlDirective`, and `FormControlName`
* to keep the view synced with the `FormControl` model.
*
* If you have imported the {@link FormsModule} or the {@link ReactiveFormsModule}, this
* If you have imported the `FormsModule` or the `ReactiveFormsModule`, this
* value accessor will be active on any select control that has a form directive. You do
* **not** need to add a special selector to activate it.
*
@ -162,7 +162,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
*
* Marks `<option>` as dynamic, so Angular can be notified when options change.
*
* See docs for {@link SelectControlValueAccessor} for usage examples.
* See docs for `SelectControlValueAccessor` for usage examples.
*
* @stable
*/

18
packages/forms/src/directives/validators.ts
View File

@ -62,7 +62,7 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = {
/**
* A Directive that adds the `required` validator to any controls marked with the
* `required` attribute, via the {@link NG_VALIDATORS} binding.
* `required` attribute, via the `NG_VALIDATORS` binding.
*
* ### Example
*
@ -100,7 +100,7 @@ export class RequiredValidator implements Validator {
/**
* A Directive that adds the `required` validator to checkbox controls marked with the
* `required` attribute, via the {@link NG_VALIDATORS} binding.
* `required` attribute, via the `NG_VALIDATORS` binding.
*
* ### Example
*
@ -123,7 +123,7 @@ export class CheckboxRequiredValidator extends RequiredValidator {
}
/**
* Provider which adds {@link EmailValidator} to {@link NG_VALIDATORS}.
* Provider which adds `EmailValidator` to `NG_VALIDATORS`.
*/
export const EMAIL_VALIDATOR: any = {
provide: NG_VALIDATORS,
@ -133,7 +133,7 @@ export const EMAIL_VALIDATOR: any = {
/**
* A Directive that adds the `email` validator to controls marked with the
* `email` attribute, via the {@link NG_VALIDATORS} binding.
* `email` attribute, via the `NG_VALIDATORS` binding.
*
* ### Example
*
@ -179,7 +179,7 @@ export interface AsyncValidatorFn {
}
/**
* Provider which adds {@link MinLengthValidator} to {@link NG_VALIDATORS}.
* Provider which adds `MinLengthValidator` to `NG_VALIDATORS`.
*
* ## Example:
*
@ -192,7 +192,7 @@ export const MIN_LENGTH_VALIDATOR: any = {
};
/**
* A directive which installs the {@link MinLengthValidator} for any `formControlName`,
* A directive which installs the `MinLengthValidator` for any `formControlName`,
* `formControl`, or control with `ngModel` that also has a `minlength` attribute.
*
* @stable
@ -228,7 +228,7 @@ export class MinLengthValidator implements Validator,
}
/**
* Provider which adds {@link MaxLengthValidator} to {@link NG_VALIDATORS}.
* Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`.
*
* ## Example:
*
@ -241,7 +241,7 @@ export const MAX_LENGTH_VALIDATOR: any = {
};
/**
* A directive which installs the {@link MaxLengthValidator} for any `formControlName,
* A directive which installs the `MaxLengthValidator` for any `formControlName,
* `formControl`,
* or control with `ngModel` that also has a `maxlength` attribute.
*
@ -287,7 +287,7 @@ export const PATTERN_VALIDATOR: any = {
/**
* A Directive that adds the `pattern` validator to any controls marked with the
* `pattern` attribute, via the {@link NG_VALIDATORS} binding. Uses attribute value
* `pattern` attribute, via the `NG_VALIDATORS` binding. Uses attribute value
* as the regex to validate Control value against. Follows pattern attribute
* semantics; i.e. regex must match entire Control value.
*

12
packages/forms/src/form_builder.ts
View File

@ -14,7 +14,7 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
/**
* @description
*
* Creates an {@link AbstractControl} from a user-specified configuration.
* 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
@ -27,17 +27,17 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model';
*
* * **npm package**: `@angular/forms`
*
* * **NgModule**: {@link ReactiveFormsModule}
* * **NgModule**: `ReactiveFormsModule`
*
* @stable
*/
@Injectable()
export class FormBuilder {
/**
* Construct a new {@link FormGroup} with the given map of configuration.
* Construct a new `FormGroup` with the given map of configuration.
* Valid keys for the `extra` parameter map are `validator` and `asyncValidator`.
*
* See the {@link FormGroup} constructor for more details.
* See the `FormGroup` constructor for more details.
*/
group(controlsConfig: {[key: string]: any}, extra: {[key: string]: any}|null = null): FormGroup {
const controls = this._reduceControls(controlsConfig);
@ -46,7 +46,7 @@ export class FormBuilder {
return new FormGroup(controls, validator, asyncValidator);
}
/**
* Construct a new {@link FormControl} with the given `formState`,`validator`, and
* Construct a new `FormControl` with the given `formState`,`validator`, and
* `asyncValidator`.
*
* `formState` can either be a standalone value for the form control or an object
@ -60,7 +60,7 @@ export class FormBuilder {
}
/**
* Construct a {@link FormArray} from the given `controlsConfig` array of
* Construct a `FormArray` from the given `controlsConfig` array of
* configuration, with the given optional `validator` and `asyncValidator`.
*/
array(

4
packages/forms/src/forms.ts
View File

@ -9,8 +9,8 @@
/**
* @module
* @description
* This module is used for handling user input, by defining and building a {@link FormGroup} that
* consists of {@link FormControl} objects, and mapping them onto the DOM. {@link FormControl}
* This module is used for handling user input, by defining and building a `FormGroup` that
* consists of `FormControl` objects, and mapping them onto the DOM. `FormControl`
* objects can then be used to read information from the form DOM elements.
*
* Forms providers are not included in default providers; you must import these providers

52
packages/forms/src/model.ts
View File

@ -83,7 +83,7 @@ export type FormHooks = 'change' | 'blur' | 'submit';
/**
* @description
*
* Interface for options provided to an {@link AbstractControl}.
* Interface for options provided to an `AbstractControl`.
*
* @experimental
*/
@ -113,7 +113,7 @@ function isOptionsObj(
/**
* @description
*
* This is the base class for {@link FormControl}, {@link FormGroup}, and {@link FormArray}.
* This is the base class for `FormControl`, `FormGroup`, and `FormArray`.
*
* It provides some of the shared behavior that all controls and groups of controls have, like
* running validators, calculating status, and resetting state. It also defines the properties
@ -676,9 +676,9 @@ export abstract class AbstractControl {
* Tracks the value and validation status of an individual form control.
*
* This is one of the three fundamental building blocks of Angular forms, along with
* {@link FormGroup} and {@link FormArray}.
* `FormGroup` and `FormArray`.
*
* When instantiating a {@link FormControl}, you can pass in an initial value as the
* When instantiating a `FormControl`, you can pass in an initial value as the
* first argument. Example:
*
* ```ts
@ -697,7 +697,7 @@ export abstract class AbstractControl {
* console.log(ctrl.status); // 'DISABLED'
* ```
*
* The second {@link FormControl} argument can accept one of three things:
* The second `FormControl` argument can accept one of three things:
* * a sync validator function
* * an array of sync validator functions
* * an options object containing validator and/or async validator functions
@ -731,7 +731,7 @@ export abstract class AbstractControl {
* You can also set `updateOn` to `'submit'`, which will delay value and validity
* updates until the parent form of the control fires a submit event.
*
* See its superclass, {@link AbstractControl}, for more properties and methods.
* See its superclass, `AbstractControl`, for more properties and methods.
*
* * **npm package**: `@angular/forms`
*
@ -911,17 +911,17 @@ export class FormControl extends AbstractControl {
/**
* @description
*
* Tracks the value and validity state of a group of {@link FormControl} instances.
* Tracks the value and validity state of a group of `FormControl` instances.
*
* A `FormGroup` aggregates the values of each child {@link FormControl} into one object,
* A `FormGroup` aggregates the values of each child `FormControl` into one object,
* with each control name as the key. It calculates its status by reducing the statuses
* of its children. For example, if one of the controls in a group is invalid, the entire
* group becomes invalid.
*
* `FormGroup` is one of the three fundamental building blocks used to define forms in Angular,
* along with {@link FormControl} and {@link FormArray}.
* along with `FormControl` and `FormArray`.
*
* When instantiating a {@link FormGroup}, pass in a collection of child controls as the first
* When instantiating a `FormGroup`, pass in a collection of child controls as the first
* argument. The key for each child will be the name under which it is registered.
*
* ### Example
@ -955,7 +955,7 @@ export class FormControl extends AbstractControl {
* }
* ```
*
* Like {@link FormControl} instances, you can alternatively choose to pass in
* Like `FormControl` instances, you can alternatively choose to pass in
* validators and async validators as part of an options object.
*
* ```
@ -1049,7 +1049,7 @@ export class FormGroup extends AbstractControl {
}
/**
* Sets the value of the {@link FormGroup}. It accepts an object that matches
* Sets the value of the `FormGroup`. It accepts an object that matches
* the structure of the group, with control names as keys.
*
* ### Example
@ -1080,7 +1080,7 @@ export class FormGroup extends AbstractControl {
}
/**
* Patches the value of the {@link FormGroup}. It accepts an object with control
* Patches the value of the `FormGroup`. It accepts an object with control
* names as keys, and will do its best to match the values to the correct controls
* in the group.
*
@ -1111,7 +1111,7 @@ export class FormGroup extends AbstractControl {
}
/**
* Resets the {@link FormGroup}. This means by default:
* Resets the `FormGroup`. This means by default:
*
* * The group and all descendants are marked `pristine`
* * The group and all descendants are marked `untouched`
@ -1152,7 +1152,7 @@ export class FormGroup extends AbstractControl {
}
/**
* The aggregate value of the {@link FormGroup}, including any disabled controls.
* The aggregate value of the `FormGroup`, including any disabled controls.
*
* If you'd like to include all values regardless of disabled status, use this method.
* Otherwise, the `value` property is the best way to get the value of the group.
@ -1254,17 +1254,17 @@ export class FormGroup extends AbstractControl {
/**
* @description
*
* Tracks the value and validity state of an array of {@link FormControl},
* {@link FormGroup} or {@link FormArray} instances.
* Tracks the value and validity state of an array of `FormControl`,
* `FormGroup` or `FormArray` instances.
*
* A `FormArray` aggregates the values of each child {@link FormControl} into an array.
* A `FormArray` aggregates the values of each child `FormControl` into an array.
* It calculates its status by reducing the statuses of its children. For example, if one of
* the controls in a `FormArray` is invalid, the entire array becomes invalid.
*
* `FormArray` is one of the three fundamental building blocks used to define forms in Angular,
* along with {@link FormControl} and {@link FormGroup}.
* along with `FormControl` and `FormGroup`.
*
* When instantiating a {@link FormArray}, pass in an array of child controls as the first
* When instantiating a `FormArray`, pass in an array of child controls as the first
* argument.
*
* ### Example
@ -1331,12 +1331,12 @@ export class FormArray extends AbstractControl {
}
/**
* Get the {@link AbstractControl} at the given `index` in the array.
* Get the `AbstractControl` at the given `index` in the array.
*/
at(index: number): AbstractControl { return this.controls[index]; }
/**
* Insert a new {@link AbstractControl} at the end of the array.
* Insert a new `AbstractControl` at the end of the array.
*/
push(control: AbstractControl): void {
this.controls.push(control);
@ -1345,7 +1345,7 @@ export class FormArray extends AbstractControl {
this._onCollectionChange();
}
/** Insert a new {@link AbstractControl} at the given `index` in the array. */
/** Insert a new `AbstractControl` at the given `index` in the array. */
insert(index: number, control: AbstractControl): void {
this.controls.splice(index, 0, control);
@ -1382,7 +1382,7 @@ export class FormArray extends AbstractControl {
get length(): number { return this.controls.length; }
/**
* Sets the value of the {@link FormArray}. It accepts an array that matches
* Sets the value of the `FormArray`. It accepts an array that matches
* the structure of the control.
*
* This method performs strict checks, so it will throw an error if you try
@ -1412,7 +1412,7 @@ export class FormArray extends AbstractControl {
}
/**
* Patches the value of the {@link FormArray}. It accepts an array that matches the
* Patches the value of the `FormArray`. It accepts an array that matches the
* structure of the control, and will do its best to match the values to the correct
* controls in the group.
*
@ -1441,7 +1441,7 @@ export class FormArray extends AbstractControl {
}
/**
* Resets the {@link FormArray}. This means by default:
* Resets the `FormArray`. This means by default:
*
* * The array and all descendants are marked `pristine`
* * The array and all descendants are marked `untouched`

8
packages/forms/src/validators.ts
View File

@ -18,7 +18,7 @@ function isEmptyInputValue(value: any): boolean {
}
/**
* Providers for validators to be used for {@link FormControl}s in a form.
* Providers for validators to be used for `FormControl`s in a form.
*
* Provide this using `multi: true` to add validators.
*
@ -41,12 +41,12 @@ function isEmptyInputValue(value: any): boolean {
export const NG_VALIDATORS = new InjectionToken<Array<Validator|Function>>('NgValidators');
/**
* Providers for asynchronous validators to be used for {@link FormControl}s
* Providers for asynchronous validators to be used for `FormControl`s
* in a form.
*
* Provide this using `multi: true` to add validators.
*
* See {@link NG_VALIDATORS} for more details.
* See `NG_VALIDATORS` for more details.
*
* @stable
*/
@ -59,7 +59,7 @@ const EMAIL_REGEXP =
/**
* Provides a set of validators used by form controls.
*
* A validator is a function that processes a {@link FormControl} or collection of
* A validator is a function that processes a `FormControl` or collection of
* controls and returns a map of errors. A null map means that validation has passed.
*
* ### Example