Skip to content

Commit

Permalink
docs: fix and add decorator api doc (#28986) (#29112)
Browse files Browse the repository at this point in the history 
PR Close #28986

PR Close #29112
  • Loading branch information
@jbogarthyde @AndrewKushnir
jbogarthyde authored and AndrewKushnir committed Mar 5, 2019
1 parent 3e08794 commit c976b88
Show file tree
Hide file tree
Showing 4 changed files with 89 additions and 71 deletions.
2 changes: 1 addition & 1 deletion packages/core/src/metadata.ts
View file
Expand Up @@ -19,5 +19,5 @@ import {ViewEncapsulation} from './metadata/view';
export {ANALYZE_FOR_ENTRY_COMPONENTS, Attribute, 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 {AfterContentChecked, AfterContentInit, AfterViewChecked, AfterViewInit, DoCheck, OnChanges, OnDestroy, OnInit} from './metadata/lifecycle_hooks';
export {CUSTOM_ELEMENTS_SCHEMA, DoBootstrap, ModuleWithProviders, NO_ERRORS_SCHEMA, NgModule, SchemaMetadata} from './metadata/ng_module';
export {CUSTOM_ELEMENTS_SCHEMA, DoBootstrap, ModuleWithProviders, NO_ERRORS_SCHEMA, NgModule, NgModuleDecorator, SchemaMetadata} from './metadata/ng_module';
export {ViewEncapsulation} from './metadata/view';
149 changes: 80 additions & 69 deletions packages/core/src/metadata/directives.ts
View file
Expand Up @@ -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
Expand Down Expand Up @@ -443,7 +443,7 @@ export interface ComponentDecorator {
*/
(obj: Component): TypeDecorator;
/**
* See the `@Component` decorator.
* See the `Component` decorator.
*/
new (obj: Component): Component;
}
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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: `
* <bank-account bankName="RBC" account-id="4747"></bank-account>
* `
* })
* class App {}
* ```
*/
(bindingPropertyName?: string): any;
new (bindingPropertyName?: string): any;
}
Expand All @@ -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: `
* <bank-account bankName="RBC" account-id="4747"></bank-account>
* `
* })
*
* class App {}
* ```
*
* The name of the DOM property to which the input property is bound.
*/
bindingPropertyName?: string;
}
Expand All @@ -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) =>
Expand Down Expand Up @@ -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
*
Expand All @@ -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;
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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;
}
Expand Down
4 changes: 3 additions & 1 deletion packages/core/src/metadata/ng_module.ts
View file
Expand Up @@ -117,10 +117,12 @@ export const NO_ERRORS_SCHEMA: SchemaMetadata = {

/**
* 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;
Expand Down
5 changes: 5 additions & 0 deletions tools/public_api_guard/core/core.d.ts
View file
Expand Up @@ -569,6 +569,11 @@ export interface NgModule {

export declare const NgModule: NgModuleDecorator;

export interface NgModuleDecorator {
(obj?: NgModule): TypeDecorator;
new (obj?: NgModule): NgModule;
}

export declare abstract class NgModuleFactory<T> {
abstract readonly moduleType: Type<T>;
abstract create(parentInjector: Injector | null): NgModuleRef<T>;
Expand Down

0 comments on commit c976b88

Please sign in to comment.