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

docs(forms): exclude internal-only methods and properties from docs (#38583) 

Prior to this commit, a lot of internal-only class properties and methods (such as `ngOnChanges`)
of the Forms package directives were exposed on angular.io website. These fields are not expected
to be called externally (they are used/invoked by framework only), since they are part of internal
implementations of the following interfaces:

* Angular lifecycle hook interfaces
* ControlValueAccessor interface
* Validator interface

Having these internal-only fields in docs creates unnecessary noise on directive detail pages.
This commit adds the `@nodoc` annotation to these properties and methods to keep fields in the
golden files, but hide them in docs.

PR Close #38583
This commit is contained in:
Andrew Kushnir 2020-08-25 16:17:57 -07:00 committed by Joey Perrott
parent de1cffb23b
commit c0523fc3b4
15 changed files with 87 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -52,23 +52,17 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
// TODO(issue/24571): remove '!'.
_asyncValidators!: any[];
/**
* @description
* An internal callback method triggered on the instance after the inputs are set.
* Registers the group with its parent group.
*/
/** @nodoc */
ngOnInit(): void {
this._checkParentType();
// Register the group with its parent group.
this.formDirective!.addFormGroup(this);
}
/**
* @description
* An internal callback method triggered before the instance is destroyed.
* Removes the group from its parent group.
*/
/** @nodoc */
ngOnDestroy(): void {
if (this.formDirective) {
// Remove the group from its parent group.
this.formDirective.removeFormGroup(this);
}
}

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

@ -47,14 +47,14 @@ export const CHECKBOX_VALUE_ACCESSOR: any = {
})
export class CheckboxControlValueAccessor implements ControlValueAccessor {
/**
* @description
* The registered callback function called when a change event occurs on the input element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -62,28 +62,23 @@ export class CheckboxControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "checked" property on the input element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: any): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'checked', value);
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (_: any) => {}): void {
this.onChange = fn;
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => {}): void {
this.onTouched = fn;
@ -91,8 +86,7 @@ export class CheckboxControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "disabled" property on the input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);

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

@ -75,14 +75,14 @@ export const COMPOSITION_BUFFER_MODE = new InjectionToken<boolean>('CompositionE
})
export class DefaultValueAccessor implements ControlValueAccessor {
/**
* @description
* The registered callback function called when an input event occurs on the input element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -99,8 +99,7 @@ export class DefaultValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: any): void {
const normalizedValue = value == null ? '' : value;
@ -108,20 +107,16 @@ export class DefaultValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (_: any) => void): void {
this.onChange = fn;
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => void): void {
this.onTouched = fn;
@ -129,8 +124,7 @@ export class DefaultValueAccessor implements ControlValueAccessor {
/**
* Sets the "disabled" property on the input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);

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

@ -137,10 +137,7 @@ export class NgForm extends ControlContainer implements Form, AfterViewInit {
new FormGroup({}, composeValidators(validators), composeAsyncValidators(asyncValidators));
}
/**
* @description
* Lifecycle method called after the view is initialized. For internal use only.
*/
/** @nodoc */
ngAfterViewInit() {
this._setUpdateStrategy();
}

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

@ -149,8 +149,8 @@ export class NgModel extends NgControl implements OnChanges, OnDestroy {
_registered = false;
/**
* @description
* Internal reference to the view model value.
* @nodoc
*/
viewModel: any;
@ -213,13 +213,7 @@ export class NgModel extends NgControl implements OnChanges, OnDestroy {
this.valueAccessor = selectValueAccessor(this, valueAccessors);
}
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges) {
this._checkForErrors();
if (!this._registered) this._setUpControl();
@ -233,11 +227,7 @@ export class NgModel extends NgControl implements OnChanges, OnDestroy {
}
}
/**
* @description
* Lifecycle method called before the directive's instance is destroyed. For internal
* use only.
*/
/** @nodoc */
ngOnDestroy(): void {
this.formDirective && this.formDirective.removeControl(this);
}

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

@ -19,7 +19,7 @@ export const NUMBER_VALUE_ACCESSOR: any = {
/**
* @description
* The `ControlValueAccessor` for writing a number value and listening to number input changes.
* The value accessor is used by the `FormControlDirective`, `FormControlName`, and `NgModel`
* The value accessor is used by the `FormControlDirective`, `FormControlName`, and `NgModel`
* directives.
*
* @usageNotes
@ -48,15 +48,15 @@ export const NUMBER_VALUE_ACCESSOR: any = {
})
export class NumberValueAccessor implements ControlValueAccessor {
/**
* @description
* The registered callback function called when a change or input event occurs on the input
* element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -64,8 +64,7 @@ export class NumberValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: number): void {
// The value needs to be normalized for IE9, otherwise it is set to 'null' when null
@ -74,10 +73,8 @@ export class NumberValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (_: number|null) => void): void {
this.onChange = (value) => {
@ -86,10 +83,8 @@ export class NumberValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => void): void {
this.onTouched = fn;
@ -97,8 +92,7 @@ export class NumberValueAccessor implements ControlValueAccessor {
/**
* Sets the "disabled" property on the input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);

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

@ -112,14 +112,14 @@ export class RadioControlValueAccessor implements ControlValueAccessor, OnDestro
_fn!: Function;
/**
* @description
* The registered callback function called when a change event occurs on the input element.
* @nodoc
*/
onChange = () => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -148,29 +148,21 @@ export class RadioControlValueAccessor implements ControlValueAccessor, OnDestro
private _renderer: Renderer2, private _elementRef: ElementRef,
private _registry: RadioControlRegistry, private _injector: Injector) {}
/**
* @description
* A lifecycle method called when the directive is initialized. For internal use only.
*/
/** @nodoc */
ngOnInit(): void {
this._control = this._injector.get(NgControl);
this._checkName();
this._registry.add(this._control, this);
}
/**
* @description
* Lifecycle method called before the directive's instance is destroyed. For internal use only.
*/
/** @nodoc */
ngOnDestroy(): void {
this._registry.remove(this);
}
/**
* @description
* Sets the "checked" property value on the radio input element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: any): void {
this._state = value === this.value;
@ -178,10 +170,8 @@ export class RadioControlValueAccessor implements ControlValueAccessor, OnDestro
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (_: any) => {}): void {
this._fn = fn;
@ -201,10 +191,8 @@ export class RadioControlValueAccessor implements ControlValueAccessor, OnDestro
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => {}): void {
this.onTouched = fn;
@ -212,8 +200,7 @@ export class RadioControlValueAccessor implements ControlValueAccessor, OnDestro
/**
* Sets the "disabled" property on the input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);

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

@ -52,15 +52,15 @@ export const RANGE_VALUE_ACCESSOR: StaticProvider = {
})
export class RangeValueAccessor implements ControlValueAccessor {
/**
* @description
* The registered callback function called when a change or input event occurs on the input
* element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -68,18 +68,15 @@ export class RangeValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: any): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'value', parseFloat(value));
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (_: number|null) => void): void {
this.onChange = (value) => {
@ -88,10 +85,8 @@ export class RangeValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => void): void {
this.onTouched = fn;
@ -99,8 +94,7 @@ export class RangeValueAccessor implements ControlValueAccessor {
/**
* Sets the "disabled" property on the range input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);

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

@ -54,8 +54,8 @@ export const formControlBinding: any = {
export class FormControlDirective extends NgControl implements OnChanges {
/**
* @description
* Internal reference to the view model value.
* @nodoc
*/
viewModel: any;
@ -116,13 +116,7 @@ export class FormControlDirective extends NgControl implements OnChanges {
this.valueAccessor = selectValueAccessor(this, valueAccessors);
}
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges): void {
if (this._isControlChanged(changes)) {
setUpControl(this.form, this);

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

@ -65,7 +65,6 @@ export const controlNameBinding: any = {
export class FormControlName extends NgControl implements OnChanges, OnDestroy {
private _added = false;
/**
* @description
* Internal reference to the view model value.
* @internal
*/
@ -142,12 +141,7 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
this.valueAccessor = selectValueAccessor(this, valueAccessors);
}
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges) {
if (!this._added) this._setUpControl();
if (isPropertyUpdated(changes, this.viewModel)) {
@ -157,10 +151,7 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
}
}
/**
* @description
* Lifecycle method called before the directive's instance is destroyed. For internal use only.
*/
/** @nodoc */
ngOnDestroy(): void {
if (this.formDirective) {
this.formDirective.removeControl(this);

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

@ -86,12 +86,7 @@ export class FormGroupDirective extends ControlContainer implements Form, OnChan
super();
}
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges): void {
this._checkFormPresent();
if (changes.hasOwnProperty('form')) {

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

@ -165,10 +165,9 @@ export class FormArrayName extends ControlContainer implements OnInit, OnDestroy
}
/**
* @description
* A lifecycle method called when the directive's inputs are initialized. For internal use only.
*
* @throws If the directive does not have a valid parent.
* @nodoc
*/
ngOnInit(): void {
this._checkParentType();
@ -176,8 +175,8 @@ export class FormArrayName extends ControlContainer implements OnInit, OnDestroy
}
/**
* @description
* A lifecycle method called before the directive's instance is destroyed. For internal use only.
* @nodoc
*/
ngOnDestroy(): void {
if (this.formDirective) {

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

@ -90,21 +90,24 @@ function _extractId(valueString: string): string {
providers: [SELECT_VALUE_ACCESSOR]
})
export class SelectControlValueAccessor implements ControlValueAccessor {
/** @nodoc */
value: any;
/** @internal */
_optionMap: Map<string, any> = new Map<string, any>();
/** @internal */
_idCounter: number = 0;
/**
* @description
* The registered callback function called when a change event occurs on the input element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -128,8 +131,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "value" property on the input element. The "selectedIndex"
* property is also set if an ID is provided on the option element.
*
* @param value The checked value
* @nodoc
*/
writeValue(value: any): void {
this.value = value;
@ -142,10 +144,8 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control value changes.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (value: any) => any): void {
this.onChange = (valueString: string) => {
@ -155,10 +155,8 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => any): void {
this.onTouched = fn;
@ -166,8 +164,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
/**
* Sets the "disabled" property on the select input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);
@ -247,10 +244,7 @@ export class NgSelectOption implements OnDestroy {
this._renderer.setProperty(this._element.nativeElement, 'value', value);
}
/**
* @description
* Lifecycle method called before the directive's instance is destroyed. For internal use only.
*/
/** @nodoc */
ngOnDestroy(): void {
if (this._select) {
this._select._optionMap.delete(this.id);

32
packages/forms/src/directives/select_multiple_control_value_accessor.ts
View File

@ -83,25 +83,26 @@ abstract class HTMLCollection {
})
export class SelectMultipleControlValueAccessor implements ControlValueAccessor {
/**
* @description
* The current value
* The current value.
* @nodoc
*/
value: any;
/** @internal */
_optionMap: Map<string, ɵNgSelectMultipleOption> = new Map<string, ɵNgSelectMultipleOption>();
/** @internal */
_idCounter: number = 0;
/**
* @description
* The registered callback function called when a change event occurs on the input element.
* @nodoc
*/
onChange = (_: any) => {};
/**
* @description
* The registered callback function called when a blur event occurs on the input element.
* @nodoc
*/
onTouched = () => {};
@ -123,11 +124,8 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
constructor(private _renderer: Renderer2, private _elementRef: ElementRef) {}
/**
* @description
* Sets the "value" property on one or of more
* of the select's options.
*
* @param value The value
* Sets the "value" property on one or of more of the select's options.
* @nodoc
*/
writeValue(value: any): void {
this.value = value;
@ -147,11 +145,9 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
}
/**
* @description
* Registers a function called when the control value changes
* and writes an array of the selected options.
*
* @param fn The callback function
* @nodoc
*/
registerOnChange(fn: (value: any) => any): void {
this.onChange = (_: any) => {
@ -181,10 +177,8 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
}
/**
* @description
* Registers a function called when the control is touched.
*
* @param fn The callback function
* @nodoc
*/
registerOnTouched(fn: () => any): void {
this.onTouched = fn;
@ -192,8 +186,7 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
/**
* Sets the "disabled" property on the select input element.
*
* @param isDisabled The disabled value
* @nodoc
*/
setDisabledState(isDisabled: boolean): void {
this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);
@ -285,10 +278,7 @@ export class ɵNgSelectMultipleOption implements OnDestroy {
this._renderer.setProperty(this._element.nativeElement, 'selected', selected);
}
/**
* @description
* Lifecycle method called before the directive's instance is destroyed. For internal use only.
*/
/** @nodoc */
ngOnDestroy(): void {
if (this._select) {
this._select._optionMap.delete(this.id);

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

@ -176,19 +176,17 @@ export class RequiredValidator implements Validator {
}
/**
* @description
* Method that validates whether the control is empty.
* Returns the validation result if enabled, otherwise null.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.required(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
* @nodoc
*/
registerOnValidatorChange(fn: () => void): void {
this._onChange = fn;
@ -225,9 +223,9 @@ export class RequiredValidator implements Validator {
})
export class CheckboxRequiredValidator extends RequiredValidator {
/**
* @description
* Method that validates whether or not the checkbox has been checked.
* Returns the validation result if enabled, otherwise null.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.requiredTrue(control) : null;
@ -286,19 +284,17 @@ export class EmailValidator implements Validator {
}
/**
* @description
* Method that validates whether an email address is valid.
* Returns the validation result if enabled, otherwise null.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this._enabled ? Validators.email(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
* @nodoc
*/
registerOnValidatorChange(fn: () => void): void {
this._onChange = fn;
@ -374,13 +370,7 @@ export class MinLengthValidator implements Validator, OnChanges {
@Input()
minlength!: string|number; // This input is always defined, since the name matches selector.
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges): void {
if ('minlength' in changes) {
this._createValidator();
@ -389,19 +379,17 @@ export class MinLengthValidator implements Validator, OnChanges {
}
/**
* @description
* Method that validates whether the value meets a minimum length
* requirement. Returns the validation result if enabled, otherwise null.
* Method that validates whether the value meets a minimum length requirement.
* Returns the validation result if enabled, otherwise null.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.minlength == null ? null : this._validator(control);
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
* @nodoc
*/
registerOnValidatorChange(fn: () => void): void {
this._onChange = fn;
@ -460,13 +448,7 @@ export class MaxLengthValidator implements Validator, OnChanges {
@Input()
maxlength!: string|number; // This input is always defined, since the name matches selector.
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges): void {
if ('maxlength' in changes) {
this._createValidator();
@ -475,19 +457,16 @@ export class MaxLengthValidator implements Validator, OnChanges {
}
/**
* @description
* Method that validates whether the value exceeds
* the maximum length requirement.
* Method that validates whether the value exceeds the maximum length requirement.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.maxlength != null ? this._validator(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
* @nodoc
*/
registerOnValidatorChange(fn: () => void): void {
this._onChange = fn;
@ -549,13 +528,7 @@ export class PatternValidator implements Validator, OnChanges {
@Input()
pattern!: string|RegExp; // This input is always defined, since the name matches selector.
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
/** @nodoc */
ngOnChanges(changes: SimpleChanges): void {
if ('pattern' in changes) {
this._createValidator();
@ -564,19 +537,16 @@ export class PatternValidator implements Validator, OnChanges {
}
/**
* @description
* Method that validates whether the value matches the
* the pattern requirement.
* Method that validates whether the value matches the the pattern requirement.
* @nodoc
*/
validate(control: AbstractControl): ValidationErrors|null {
return this._validator(control);
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
* @nodoc
*/
registerOnValidatorChange(fn: () => void): void {
this._onChange = fn;