cargdev/angular
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
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.
*