From 982bc7f2aab991c1d0aab2b07befb6087c5706b8 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 19 Oct 2018 17:36:24 +0100 Subject: [PATCH] docs: update forms with `@publicApi` tags (#26595) PR Close #26595 --- .../src/directives/abstract_control_directive.ts | 1 + .../src/directives/abstract_form_group_directive.ts | 1 + .../forms/src/directives/checkbox_value_accessor.ts | 1 + packages/forms/src/directives/control_container.ts | 2 ++ .../forms/src/directives/control_value_accessor.ts | 3 +++ .../forms/src/directives/default_value_accessor.ts | 1 + packages/forms/src/directives/form_interface.ts | 2 ++ packages/forms/src/directives/ng_control.ts | 2 ++ packages/forms/src/directives/ng_control_status.ts | 2 ++ packages/forms/src/directives/ng_form.ts | 1 + .../forms/src/directives/ng_form_selector_warning.ts | 1 + packages/forms/src/directives/ng_model.ts | 1 + packages/forms/src/directives/ng_model_group.ts | 1 + .../src/directives/radio_control_value_accessor.ts | 1 + .../reactive_directives/form_control_directive.ts | 1 + .../reactive_directives/form_control_name.ts | 1 + .../reactive_directives/form_group_directive.ts | 1 + .../reactive_directives/form_group_name.ts | 2 ++ .../src/directives/select_control_value_accessor.ts | 2 ++ .../select_multiple_control_value_accessor.ts | 1 + packages/forms/src/directives/validators.ts | 12 ++++++++++++ packages/forms/src/form_builder.ts | 1 + packages/forms/src/form_providers.ts | 3 +++ packages/forms/src/model.ts | 8 ++++++-- packages/forms/src/validators.ts | 3 +++ packages/forms/src/version.ts | 3 +++ tools/public_api_guard/forms/forms.d.ts | 6 ------ 27 files changed, 56 insertions(+), 8 deletions(-) diff --git a/packages/forms/src/directives/abstract_control_directive.ts b/packages/forms/src/directives/abstract_control_directive.ts index d0884eeeb4..992eeb118f 100644 --- a/packages/forms/src/directives/abstract_control_directive.ts +++ b/packages/forms/src/directives/abstract_control_directive.ts @@ -16,6 +16,7 @@ import {ValidationErrors} from './validators'; * * This class is only used internally in the `ReactiveFormsModule` and the `FormsModule`. * + * @publicApi */ export abstract class AbstractControlDirective { /** diff --git a/packages/forms/src/directives/abstract_form_group_directive.ts b/packages/forms/src/directives/abstract_form_group_directive.ts index 7b423588be..a16752dbf3 100644 --- a/packages/forms/src/directives/abstract_form_group_directive.ts +++ b/packages/forms/src/directives/abstract_form_group_directive.ts @@ -21,6 +21,7 @@ import {AsyncValidatorFn, ValidatorFn} from './validators'; * @description * A base class for code shared between the `NgModelGroup` and `FormGroupName` directives. * + * @publicApi */ export class AbstractFormGroupDirective extends ControlContainer implements OnInit, OnDestroy { /** diff --git a/packages/forms/src/directives/checkbox_value_accessor.ts b/packages/forms/src/directives/checkbox_value_accessor.ts index 123364cf73..a1e8ec0614 100644 --- a/packages/forms/src/directives/checkbox_value_accessor.ts +++ b/packages/forms/src/directives/checkbox_value_accessor.ts @@ -28,6 +28,7 @@ export const CHECKBOX_VALUE_ACCESSOR: any = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: diff --git a/packages/forms/src/directives/control_container.ts b/packages/forms/src/directives/control_container.ts index 747a6b11ca..13dc6376a8 100644 --- a/packages/forms/src/directives/control_container.ts +++ b/packages/forms/src/directives/control_container.ts @@ -14,6 +14,8 @@ import {Form} from './form_interface'; * @description * A base class for directives that contain multiple registered instances of `NgControl`. * Only used by the forms module. + * + * @publicApi */ export abstract class ControlContainer extends AbstractControlDirective { /** diff --git a/packages/forms/src/directives/control_value_accessor.ts b/packages/forms/src/directives/control_value_accessor.ts index c58dce5786..f153f30d63 100644 --- a/packages/forms/src/directives/control_value_accessor.ts +++ b/packages/forms/src/directives/control_value_accessor.ts @@ -17,6 +17,8 @@ import {InjectionToken} from '@angular/core'; * that integrates with Angular forms. * * @see DefaultValueAccessor + * + * @publicApi */ export interface ControlValueAccessor { /** @@ -134,5 +136,6 @@ export interface ControlValueAccessor { * * See `DefaultValueAccessor` for how to implement one. * + * @publicApi */ export const NG_VALUE_ACCESSOR = new InjectionToken('NgValueAccessor'); diff --git a/packages/forms/src/directives/default_value_accessor.ts b/packages/forms/src/directives/default_value_accessor.ts index 78a3a4a2dc..f4d172d49e 100644 --- a/packages/forms/src/directives/default_value_accessor.ts +++ b/packages/forms/src/directives/default_value_accessor.ts @@ -44,6 +44,7 @@ export const COMPOSITION_BUFFER_MODE = new InjectionToken('CompositionE * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: diff --git a/packages/forms/src/directives/form_interface.ts b/packages/forms/src/directives/form_interface.ts index f58e60ddfd..e4a19009f3 100644 --- a/packages/forms/src/directives/form_interface.ts +++ b/packages/forms/src/directives/form_interface.ts @@ -18,6 +18,8 @@ import {NgControl} from './ng_control'; * An interface implemented by `FormGroupDirective` and `NgForm` directives. * * Only used by the `ReactiveFormsModule` and `FormsModule`. + * + * @publicApi */ export interface Form { /** diff --git a/packages/forms/src/directives/ng_control.ts b/packages/forms/src/directives/ng_control.ts index 2affcbe0fa..0314773902 100644 --- a/packages/forms/src/directives/ng_control.ts +++ b/packages/forms/src/directives/ng_control.ts @@ -20,6 +20,8 @@ function unimplemented(): any { * @description * A base class that all control `FormControl`-based directives extend. It binds a `FormControl` * object to a DOM element. + * + * @publicApi */ export abstract class NgControl extends AbstractControlDirective { /** diff --git a/packages/forms/src/directives/ng_control_status.ts b/packages/forms/src/directives/ng_control_status.ts index 769b052459..9138101731 100644 --- a/packages/forms/src/directives/ng_control_status.ts +++ b/packages/forms/src/directives/ng_control_status.ts @@ -51,6 +51,7 @@ export const ngControlStatusHost = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: '[formControlName],[ngModel],[formControl]', host: ngControlStatusHost}) export class NgControlStatus extends AbstractControlStatus { @@ -63,6 +64,7 @@ export class NgControlStatus extends AbstractControlStatus { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: diff --git a/packages/forms/src/directives/ng_form.ts b/packages/forms/src/directives/ng_form.ts index 1f4c76fa64..4f3de9bb2d 100644 --- a/packages/forms/src/directives/ng_form.ts +++ b/packages/forms/src/directives/ng_form.ts @@ -74,6 +74,7 @@ const resolvedPromise = Promise.resolve(null); * {@example forms/ts/simpleForm/simple_form_example.ts region='Component'} * * @ngModule FormsModule + * @publicApi */ @Directive({ selector: 'form:not([ngNoForm]):not([formGroup]),ngForm,ng-form,[ngForm]', diff --git a/packages/forms/src/directives/ng_form_selector_warning.ts b/packages/forms/src/directives/ng_form_selector_warning.ts index 7124a8f143..30d1767827 100644 --- a/packages/forms/src/directives/ng_form_selector_warning.ts +++ b/packages/forms/src/directives/ng_form_selector_warning.ts @@ -19,6 +19,7 @@ export const NG_FORM_SELECTOR_WARNING = new InjectionToken('NgFormSelectorWarnin * * @deprecated in Angular v6 and will be removed in Angular v9. * @ngModule FormsModule + * @publicApi */ @Directive({selector: 'ngForm'}) export class NgFormSelectorWarning { diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts index 2b7c1cd770..ae965f22cb 100644 --- a/packages/forms/src/directives/ng_model.ts +++ b/packages/forms/src/directives/ng_model.ts @@ -98,6 +98,7 @@ const resolvedPromise = Promise.resolve(null); * * Selects: `SelectControlValueAccessor` * * @ngModule FormsModule + * @publicApi */ @Directive({ selector: '[ngModel]:not([formControlName]):not([formControl])', diff --git a/packages/forms/src/directives/ng_model_group.ts b/packages/forms/src/directives/ng_model_group.ts index cdd58c20bd..b1e49b4b02 100644 --- a/packages/forms/src/directives/ng_model_group.ts +++ b/packages/forms/src/directives/ng_model_group.ts @@ -40,6 +40,7 @@ export const modelGroupProvider: any = { * {@example forms/ts/ngModelGroup/ng_model_group_example.ts region='Component'} * * @ngModule FormsModule + * @publicApi */ @Directive({selector: '[ngModelGroup]', providers: [modelGroupProvider], exportAs: 'ngModelGroup'}) export class NgModelGroup extends AbstractFormGroupDirective implements OnInit, OnDestroy { diff --git a/packages/forms/src/directives/radio_control_value_accessor.ts b/packages/forms/src/directives/radio_control_value_accessor.ts index 7db67cdada..3d88f36ed9 100644 --- a/packages/forms/src/directives/radio_control_value_accessor.ts +++ b/packages/forms/src/directives/radio_control_value_accessor.ts @@ -82,6 +82,7 @@ export class RadioControlRegistry { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: diff --git a/packages/forms/src/directives/reactive_directives/form_control_directive.ts b/packages/forms/src/directives/reactive_directives/form_control_directive.ts index d2e2797df2..9ee732b060 100644 --- a/packages/forms/src/directives/reactive_directives/form_control_directive.ts +++ b/packages/forms/src/directives/reactive_directives/form_control_directive.ts @@ -133,6 +133,7 @@ export const formControlBinding: any = { * the pattern is being used as the code is being updated. * * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: '[formControl]', providers: [formControlBinding], exportAs: 'ngForm'}) diff --git a/packages/forms/src/directives/reactive_directives/form_control_name.ts b/packages/forms/src/directives/reactive_directives/form_control_name.ts index 999b9b55cf..737f2e81e0 100644 --- a/packages/forms/src/directives/reactive_directives/form_control_name.ts +++ b/packages/forms/src/directives/reactive_directives/form_control_name.ts @@ -145,6 +145,7 @@ export const controlNameBinding: any = { * the pattern is being used as the code is being updated. * * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: '[formControlName]', providers: [controlNameBinding]}) export class FormControlName extends NgControl implements OnChanges, OnDestroy { diff --git a/packages/forms/src/directives/reactive_directives/form_group_directive.ts b/packages/forms/src/directives/reactive_directives/form_group_directive.ts index fe524d7fcc..9db4ac995c 100644 --- a/packages/forms/src/directives/reactive_directives/form_group_directive.ts +++ b/packages/forms/src/directives/reactive_directives/form_group_directive.ts @@ -54,6 +54,7 @@ export const formDirectiveProvider: any = { * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'} * * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: '[formGroup]', diff --git a/packages/forms/src/directives/reactive_directives/form_group_name.ts b/packages/forms/src/directives/reactive_directives/form_group_name.ts index 2e2d4f394b..c079dd901a 100644 --- a/packages/forms/src/directives/reactive_directives/form_group_name.ts +++ b/packages/forms/src/directives/reactive_directives/form_group_name.ts @@ -63,6 +63,7 @@ export const formGroupNameProvider: any = { * {@example forms/ts/nestedFormGroup/nested_form_group_example.ts region='Component'} * * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: '[formGroupName]', providers: [formGroupNameProvider]}) export class FormGroupName extends AbstractFormGroupDirective implements OnInit, OnDestroy { @@ -135,6 +136,7 @@ export const formArrayNameProvider: any = { * {@example forms/ts/nestedFormArray/nested_form_array_example.ts region='Component'} * * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: '[formArrayName]', providers: [formArrayNameProvider]}) export class FormArrayName extends ControlContainer implements OnInit, OnDestroy { diff --git a/packages/forms/src/directives/select_control_value_accessor.ts b/packages/forms/src/directives/select_control_value_accessor.ts index 9be4c1cb15..92945370ff 100644 --- a/packages/forms/src/directives/select_control_value_accessor.ts +++ b/packages/forms/src/directives/select_control_value_accessor.ts @@ -88,6 +88,7 @@ function _extractId(valueString: string): string { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: @@ -166,6 +167,7 @@ export class SelectControlValueAccessor implements ControlValueAccessor { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({selector: 'option'}) export class NgSelectOption implements OnDestroy { diff --git a/packages/forms/src/directives/select_multiple_control_value_accessor.ts b/packages/forms/src/directives/select_multiple_control_value_accessor.ts index 7e9b946905..21bdcdab90 100644 --- a/packages/forms/src/directives/select_multiple_control_value_accessor.ts +++ b/packages/forms/src/directives/select_multiple_control_value_accessor.ts @@ -71,6 +71,7 @@ abstract class HTMLCollection { * * @ngModule ReactiveFormsModule * @ngModule FormsModule + * @publicApi */ @Directive({ selector: diff --git a/packages/forms/src/directives/validators.ts b/packages/forms/src/directives/validators.ts index d446204284..210ac90432 100644 --- a/packages/forms/src/directives/validators.ts +++ b/packages/forms/src/directives/validators.ts @@ -45,6 +45,8 @@ export type ValidationErrors = { * } * } * ``` + * + * @publicApi */ export interface Validator { /** @@ -135,6 +137,7 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: @@ -240,8 +243,14 @@ export class EmailValidator implements Validator { registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } +/** + * @publicApi + */ export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; } +/** + * @publicApi + */ export interface AsyncValidatorFn { (control: AbstractControl): Promise|Observable; } @@ -266,6 +275,7 @@ export const MIN_LENGTH_VALIDATOR: any = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: '[minlength][formControlName],[minlength][formControl],[minlength][ngModel]', @@ -320,6 +330,7 @@ export const MAX_LENGTH_VALIDATOR: any = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: '[maxlength][formControlName],[maxlength][formControl],[maxlength][ngModel]', @@ -377,6 +388,7 @@ export const PATTERN_VALIDATOR: any = { * * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @publicApi */ @Directive({ selector: '[pattern][formControlName],[pattern][formControl],[pattern][ngModel]', diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts index 9b3c4570ec..dc4825c3f9 100644 --- a/packages/forms/src/form_builder.ts +++ b/packages/forms/src/form_builder.ts @@ -21,6 +21,7 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model'; * * @see [Reactive Forms Guide](/guide/reactive-forms) * + * @publicApi */ @Injectable() export class FormBuilder { diff --git a/packages/forms/src/form_providers.ts b/packages/forms/src/form_providers.ts index 56f7f42bf9..0968dfa982 100644 --- a/packages/forms/src/form_providers.ts +++ b/packages/forms/src/form_providers.ts @@ -18,6 +18,8 @@ import {FormBuilder} from './form_builder'; * @see [Forms](guide/forms) * * @see [Forms Guide](/guide/forms) + * + * @publicApi */ @NgModule({ declarations: TEMPLATE_DRIVEN_DIRECTIVES, @@ -51,6 +53,7 @@ export class FormsModule { * * @see [Reactive Forms Guide](/guide/reactive-forms) * + * @publicApi */ @NgModule({ declarations: [REACTIVE_DRIVEN_DIRECTIVES], diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index 94cf381d6f..076a29ebf9 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -130,6 +130,7 @@ function isOptionsObj( * @see [Reactive Forms Guide](/guide/reactive-forms) * @see [Dynamic Forms Guide](/guide/dynamic-form) * + * @publicApi */ export abstract class AbstractControl { /** @internal */ @@ -868,7 +869,8 @@ export abstract class AbstractControl { * console.log(control.value); // 'Drew' * console.log(control.status); // 'DISABLED' * -*/ + * @publicApi + */ export class FormControl extends AbstractControl { /** @internal */ _onChange: Function[] = []; @@ -1124,6 +1126,8 @@ export class FormControl extends AbstractControl { * one: new FormControl() * }, { updateOn: 'blur' }); * ``` + * + * @publicApi */ export class FormGroup extends AbstractControl { /** @@ -1540,7 +1544,7 @@ export class FormGroup extends AbstractControl { * the `FormArray` directly, as that result in strange and unexpected behavior such * as broken change detection. * - * + * @publicApi */ export class FormArray extends AbstractControl { /** diff --git a/packages/forms/src/validators.ts b/packages/forms/src/validators.ts index b2bc969901..aa742aeea2 100644 --- a/packages/forms/src/validators.ts +++ b/packages/forms/src/validators.ts @@ -42,6 +42,7 @@ function isEmptyInputValue(value: any): boolean { * } * ``` * + * @publicApi */ export const NG_VALIDATORS = new InjectionToken>('NgValidators'); @@ -51,6 +52,7 @@ export const NG_VALIDATORS = new InjectionToken>('NgVa * * @see `NG_VALIDATORS` * + * @publicApi */ export const NG_ASYNC_VALIDATORS = new InjectionToken>('NgAsyncValidators'); @@ -67,6 +69,7 @@ const EMAIL_REGEXP = * * @see [Form Validation](/guide/form-validation) * + * @publicApi */ export class Validators { /** diff --git a/packages/forms/src/version.ts b/packages/forms/src/version.ts index af66f0fa27..9469ebe5e5 100644 --- a/packages/forms/src/version.ts +++ b/packages/forms/src/version.ts @@ -14,4 +14,7 @@ import {Version} from '@angular/core'; +/** + * @publicApi + */ export const VERSION = new Version('0.0.0-PLACEHOLDER'); diff --git a/tools/public_api_guard/forms/forms.d.ts b/tools/public_api_guard/forms/forms.d.ts index d725f24576..1406341355 100644 --- a/tools/public_api_guard/forms/forms.d.ts +++ b/tools/public_api_guard/forms/forms.d.ts @@ -85,7 +85,6 @@ export declare abstract class AbstractControlDirective { reset(value?: any): void; } -/** @experimental */ export interface AbstractControlOptions { asyncValidators?: AsyncValidatorFn | AsyncValidatorFn[] | null; updateOn?: 'change' | 'blur' | 'submit'; @@ -102,7 +101,6 @@ export declare class AbstractFormGroupDirective extends ControlContainer impleme ngOnInit(): void; } -/** @experimental */ export interface AsyncValidator extends Validator { validate(control: AbstractControl): Promise | Observable; } @@ -121,12 +119,10 @@ export declare class CheckboxControlValueAccessor implements ControlValueAccesso writeValue(value: any): void; } -/** @experimental */ export declare class CheckboxRequiredValidator extends RequiredValidator { validate(control: AbstractControl): ValidationErrors | null; } -/** @experimental */ export declare const COMPOSITION_BUFFER_MODE: InjectionToken; export declare abstract class ControlContainer extends AbstractControlDirective { @@ -152,7 +148,6 @@ export declare class DefaultValueAccessor implements ControlValueAccessor { writeValue(value: any): void; } -/** @experimental */ export declare class EmailValidator implements Validator { email: boolean | string; registerOnValidatorChange(fn: () => void): void; @@ -498,7 +493,6 @@ export declare class SelectMultipleControlValueAccessor implements ControlValueA writeValue(value: any): void; } -/** @experimental */ export declare type ValidationErrors = { [key: string]: any; };