diff --git a/packages/core/src/di/metadata.ts b/packages/core/src/di/metadata.ts index 95c090bda3..33a6c94204 100644 --- a/packages/core/src/di/metadata.ts +++ b/packages/core/src/di/metadata.ts @@ -237,12 +237,10 @@ export const Host: HostDecorator = makeParamDecorator('Host'); */ export interface AttributeDecorator { /** - * Specifies that a constant attribute value should be injected. - * - * The directive can inject constant string literals of host element attributes. + * A parameter decorator for a directive constructor that designates + * a host-element attribute whose value is injected as a constant string literal. * * @usageNotes - * ### Example * * Suppose we have an `` element and want to know its `type`. * @@ -250,7 +248,7 @@ export interface AttributeDecorator { * * ``` * - * A decorator can inject string literal `text` like so: + * The following example uses the decorator to inject the string literal `text`. * * {@example core/ts/metadata/metadata.ts region='attributeMetadata'} * @@ -258,20 +256,6 @@ export interface AttributeDecorator { * * {@example core/ts/metadata/metadata.ts region='attributeFactory'} * - * ### Example as ES5 annotation - * - * ``` - * var MyComponent = function(title) { - * ... - * }; - * - * MyComponent.annotations = [ - * new ng.Component({...}) - * ] - * MyComponent.parameters = [ - * [new ng.Attribute('title')] - * ] - * ``` */ (name: string): any; new (name: string): Attribute; @@ -282,7 +266,12 @@ export interface AttributeDecorator { * * @publicApi */ -export interface Attribute { attributeName?: string; } +export interface Attribute { + /** + * The name of the attribute whose value can be injected. + */ + attributeName?: string; +} /** * Attribute decorator and metadata. diff --git a/packages/core/src/metadata.ts b/packages/core/src/metadata.ts index 54caf289d5..75fa6c5191 100644 --- a/packages/core/src/metadata.ts +++ b/packages/core/src/metadata.ts @@ -22,6 +22,6 @@ export {Attribute} from './di'; export {AfterContentChecked, AfterContentInit, AfterViewChecked, AfterViewInit, DoCheck, OnChanges, OnDestroy, OnInit} from './interface/lifecycle_hooks'; export {ANALYZE_FOR_ENTRY_COMPONENTS, ContentChild, ContentChildDecorator, ContentChildren, ContentChildrenDecorator, Query, ViewChild, ViewChildDecorator, ViewChildren, ViewChildrenDecorator} from './metadata/di'; export {Component, ComponentDecorator, Directive, DirectiveDecorator, HostBinding, HostBindingDecorator, HostListener, HostListenerDecorator, Input, InputDecorator, Output, OutputDecorator, Pipe, PipeDecorator} from './metadata/directives'; -export {DoBootstrap, ModuleWithProviders, NgModule} from './metadata/ng_module'; +export {DoBootstrap, ModuleWithProviders, NgModule, NgModuleDecorator} from './metadata/ng_module'; export {CUSTOM_ELEMENTS_SCHEMA, NO_ERRORS_SCHEMA, SchemaMetadata} from './metadata/schema'; export {ViewEncapsulation} from './metadata/view'; diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index e03c91ee46..f25f627622 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -317,7 +317,7 @@ export interface ComponentDecorator { * * A component must belong to an NgModule in order for it to be available * to another component or application. To make it a member of an NgModule, - * list it in the `declarations` field of the `@NgModule` metadata. + * list it in the `declarations` field of the `NgModule` metadata. * * Note that, in addition to these options for configuring a directive, * you can control a component's runtime behavior by implementing @@ -443,7 +443,7 @@ export interface ComponentDecorator { */ (obj: Component): TypeDecorator; /** - * See the `@Component` decorator. + * See the `Component` decorator. */ new (obj: Component): Component; } @@ -572,7 +572,22 @@ export const Component: ComponentDecorator = makeDecorator( */ export interface PipeDecorator { /** - * Declares a reusable pipe function, and supplies configuration metadata. + * + * Decorator that marks a class as pipe and supplies configuration metadata. + * + * A pipe class must implement the `PipeTransform` interface. + * For example, if the name is "myPipe", use a template binding expression + * such as the following: + * + * ``` + * {{ exp | myPipe }} + * ``` + * + * The result of the expression is passed to the pipe's `transform()` method. + * + * A pipe must belong to an NgModule in order for it to be available + * to a template. To make it a member of an NgModule, + * list it in the `declarations` field of the `NgModule` metadata. * */ (obj: Pipe): TypeDecorator; @@ -622,23 +637,48 @@ export const Pipe: PipeDecorator = makeDecorator( */ export interface InputDecorator { /** - * Decorator that marks a class as pipe and supplies configuration metadata. - * - * A pipe class must implement the `PipeTransform` interface. - * For example, if the name is "myPipe", use a template binding expression - * such as the following: - * - * ``` - * {{ exp | myPipe }} - * ``` - * - * The result of the expression is passed to the pipe's `transform()` method. - * - * A pipe must belong to an NgModule in order for it to be available - * to a template. To make it a member of an NgModule, - * list it in the `declarations` field of the `@NgModule` metadata. - * - */ + * Decorator that marks a class field as an input property and supplies configuration metadata. + * The input property is bound to a DOM property in the template. During change detection, + * Angular automatically updates the data property with the DOM property's value. + * + * @usageNotes + * + * You can supply an optional name to use in templates when the + * component is instantiated, that maps to the + * name of the bound property. By default, the original + * name of the bound property is used for input binding. + * + * The following example creates a component with two input properties, + * one of which is given a special binding name. + * + * ```typescript + * @Component({ + * selector: 'bank-account', + * template: ` + * Bank Name: {{bankName}} + * Account Id: {{id}} + * ` + * }) + * class BankAccount { + * // This property is bound using its original name. + * @Input() bankName: string; + * // this property value is bound to a different property name + * // when this component is instantiated in a template. + * @Input('account-id') id: string; + * + * // this property is not bound, and is not automatically updated by Angular + * normalizedBankName: string; + * } + * + * @Component({ + * selector: 'app', + * template: ` + * + * ` + * }) + * class App {} + * ``` + */ (bindingPropertyName?: string): any; new (bindingPropertyName?: string): any; } @@ -650,49 +690,7 @@ export interface InputDecorator { */ export interface Input { /** - * Decorator that marks a class field as an input property and supplies configuration metadata. - * Declares a data-bound input property, which Angular automatically updates - * during change detection. - * - * @usageNotes - * - * You can supply an optional name to use in templates when the - * component is instantiated, that maps to the - * name of the bound property. By default, the original - * name of the bound property is used for input binding. - * - * The following example creates a component with two input properties, - * one of which is given a special binding name. - * - * ```typescript - * @Component({ - * selector: 'bank-account', - * template: ` - * Bank Name: {{bankName}} - * Account Id: {{id}} - * ` - * }) - * class BankAccount { - * // This property is bound using its original name. - * @Input() bankName: string; - * // this property value is bound to a different property name - * // when this component is instantiated in a template. - * @Input('account-id') id: string; - * - * // this property is not bound, and is not automatically updated by Angular - * normalizedBankName: string; - * } - * - * @Component({ - * selector: 'app', - * template: ` - * - * ` - * }) - * - * class App {} - * ``` - * + * The name of the DOM property to which the input property is bound. */ bindingPropertyName?: string; } @@ -715,7 +713,7 @@ const initializeBaseDef = (target: any): void => { }; /** - * Does the work of creating the `ngBaseDef` property for the @Input and @Output decorators. + * Does the work of creating the `ngBaseDef` property for the `Input` and `Output` decorators. * @param key "inputs" or "outputs" */ const updateBaseDefFromIOProp = (getProp: (baseDef: {inputs?: any, outputs?: any}) => any) => @@ -747,8 +745,7 @@ export const Input: InputDecorator = makePropDecorator( export interface OutputDecorator { /** * Decorator that marks a class field as an output property and supplies configuration metadata. - * Declares a data-bound output property, which Angular automatically updates - * during change detection. + * The DOM property bound to the output property is automatically updated during change detection. * * @usageNotes * @@ -757,7 +754,7 @@ export interface OutputDecorator { * name of the bound property. By default, the original * name of the bound property is used for output binding. * - * See `@Input` decorator for an example of providing a binding name. + * See `Input` decorator for an example of providing a binding name. * */ (bindingPropertyName?: string): any; @@ -769,7 +766,12 @@ export interface OutputDecorator { * * @publicApi */ -export interface Output { bindingPropertyName?: string; } +export interface Output { + /** + * The name of the DOM property to which the output property is bound. + */ + bindingPropertyName?: string; +} /** * @Annotation @@ -825,7 +827,12 @@ export interface HostBindingDecorator { * * @publicApi */ -export interface HostBinding { hostPropertyName?: string; } +export interface HostBinding { + /** + * The DOM property that is bound to a data property. + */ + hostPropertyName?: string; +} /** * @Annotation @@ -841,6 +848,10 @@ export const HostBinding: HostBindingDecorator = * @publicApi */ export interface HostListenerDecorator { + /** + * Decorator that declares a DOM event to listen for, + * and provides a handler method to run when that event occurs. + */ (eventName: string, args?: string[]): any; new (eventName: string, args?: string[]): any; } diff --git a/packages/core/src/metadata/ng_module.ts b/packages/core/src/metadata/ng_module.ts index b2c3a3ee82..c1b9312389 100644 --- a/packages/core/src/metadata/ng_module.ts +++ b/packages/core/src/metadata/ng_module.ts @@ -91,10 +91,12 @@ export interface ModuleWithProviders< /** * Type of the NgModule decorator / constructor function. + * + * @publicApi */ export interface NgModuleDecorator { /** - * Marks a class as an NgModule and supplies configuration metadata. + * Decorator that marks a class as an NgModule and supplies configuration metadata. */ (obj?: NgModule): TypeDecorator; new (obj?: NgModule): NgModule; diff --git a/tools/public_api_guard/core/core.d.ts b/tools/public_api_guard/core/core.d.ts index 55d373fd8f..329a3a23e5 100644 --- a/tools/public_api_guard/core/core.d.ts +++ b/tools/public_api_guard/core/core.d.ts @@ -574,6 +574,11 @@ export interface NgModule { export declare const NgModule: NgModuleDecorator; +export interface NgModuleDecorator { + (obj?: NgModule): TypeDecorator; + new (obj?: NgModule): NgModule; +} + export declare abstract class NgModuleFactory { abstract readonly moduleType: Type; abstract create(parentInjector: Injector | null): NgModuleRef;