From 40aaa42f445c0d2600a219d1a83834db510a2eab Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Mon, 1 Jul 2019 12:31:42 -0700 Subject: [PATCH] docs: api doc cleanup (#31377) PR Close #31377 --- .../src/change_detection/pipe_transform.ts | 8 +- packages/core/src/di/injectable.ts | 5 +- packages/core/src/di/interface/provider.ts | 121 +++++++----------- packages/core/src/di/metadata.ts | 32 +++-- packages/core/src/event_emitter.ts | 11 +- packages/core/src/linker/component_factory.ts | 10 +- .../src/linker/component_factory_resolver.ts | 10 ++ packages/core/src/metadata/di.ts | 112 ++++++++-------- packages/core/src/metadata/directives.ts | 39 +++--- packages/core/src/util/decorators.ts | 9 +- .../ts/contentChild/content_child_example.ts | 6 +- .../content_children_example.ts | 5 +- .../contentChildren/content_children_howto.ts | 1 - packages/examples/core/di/ts/provider_spec.ts | 8 +- .../di/ts/viewChild/view_child_example.ts | 7 +- .../core/di/ts/viewChild/view_child_howto.ts | 1 - .../ts/viewChildren/view_children_example.ts | 8 +- .../di/ts/viewChildren/view_children_howto.ts | 1 - 18 files changed, 184 insertions(+), 210 deletions(-) diff --git a/packages/core/src/change_detection/pipe_transform.ts b/packages/core/src/change_detection/pipe_transform.ts index d52593b83f..3a6889e3a8 100644 --- a/packages/core/src/change_detection/pipe_transform.ts +++ b/packages/core/src/change_detection/pipe_transform.ts @@ -7,17 +7,15 @@ */ /** - * To create a Pipe, you must implement this interface. - * + * An interface that is implemented by pipes in order to perform a transformation. * Angular invokes the `transform` method with the value of a binding * as the first argument, and any parameters as the second argument in list form. * * @usageNotes - * ### Example * - * The `RepeatPipe` below repeats the value as many times as indicated by the first argument: + * In the following example, `RepeatPipe` repeats a given value a given number of times. * - * ``` + * ```ts * import {Pipe, PipeTransform} from '@angular/core'; * * @Pipe({name: 'repeat'}) diff --git a/packages/core/src/di/injectable.ts b/packages/core/src/di/injectable.ts index eb6fd4782b..f79906235b 100644 --- a/packages/core/src/di/injectable.ts +++ b/packages/core/src/di/injectable.ts @@ -31,7 +31,7 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider | */ export interface InjectableDecorator { /** - * Marks a class as available to `Injector` for creation. + * Decorator that marks a class as available to `Injector` for creation. * * @see [Introduction to Services and DI](guide/architecture-services) * @see [Dependency Injection Guide](guide/dependency-injection) @@ -41,7 +41,8 @@ export interface InjectableDecorator { * The following example shows how service classes are properly marked as * injectable. * - * + * * */ (): TypeDecorator; diff --git a/packages/core/src/di/interface/provider.ts b/packages/core/src/di/interface/provider.ts index d518cce9e5..190d89164b 100644 --- a/packages/core/src/di/interface/provider.ts +++ b/packages/core/src/di/interface/provider.ts @@ -23,29 +23,28 @@ export interface ValueSansProvider { /** * Configures the `Injector` to return a value for a token. - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * * ### Example * - * {@example core/di/ts/provider_spec.ts region='ValueProvider'} + * {@example core/di/ts/provider_spec.ts region='ValueProvider' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ export interface ValueProvider extends ValueSansProvider { /** - * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`). + * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`. */ provide: any; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; @@ -59,13 +58,13 @@ export interface ValueProvider extends ValueSansProvider { */ export interface StaticClassSansProvider { /** - * An optional class to instantiate for the `token`. (If not provided `provide` is assumed to be a - * class to instantiate) + * An optional class to instantiate for the `token`. By default, the `provide` + * class is instantiated. */ useClass: Type; /** - * A list of `token`s which need to be resolved by the injector. The list of values is then + * A list of `token`s to be resolved by the injector. The list of values is then * used as arguments to the `useClass` constructor. */ deps: any[]; @@ -73,33 +72,30 @@ export interface StaticClassSansProvider { /** * Configures the `Injector` to return an instance of `useClass` for a token. - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * * {@example core/di/ts/provider_spec.ts region='StaticClassProvider'} * * Note that following two providers are not equal: * - * {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference'} + * {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ export interface StaticClassProvider extends StaticClassSansProvider { /** - * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`). + * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`. */ provide: any; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; @@ -108,13 +104,11 @@ export interface StaticClassProvider extends StaticClassSansProvider { /** * Configures the `Injector` to return an instance of a token. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * - * ``` + * ```ts * @Injectable(SomeModule, {deps: []}) * class MyService {} * ``` @@ -123,8 +117,7 @@ export interface StaticClassProvider extends StaticClassSansProvider { */ export interface ConstructorSansProvider { /** - * A list of `token`s which need to be resolved by the injector. The list of values is then - * used as arguments to the `useClass` constructor. + * A list of `token`s to be resolved by the injector. */ deps?: any[]; } @@ -132,28 +125,26 @@ export interface ConstructorSansProvider { /** * Configures the `Injector` to return an instance of a token. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'} + * {@example core/di/ts/provider_spec.ts region='ConstructorProvider' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ export interface ConstructorProvider extends ConstructorSansProvider { /** - * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`). + * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`. */ provide: Type; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; @@ -162,13 +153,14 @@ export interface ConstructorProvider extends ConstructorSansProvider { /** * Configures the `Injector` to return a value of another `useExisting` token. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see `ExistingProvider` + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @publicApi */ export interface ExistingSansProvider { /** - * Existing `token` to return. (equivalent to `injector.get(useExisting)`) + * Existing `token` to return. (Equivalent to `injector.get(useExisting)`) */ useExisting: any; } @@ -176,28 +168,26 @@ export interface ExistingSansProvider { /** * Configures the `Injector` to return a value of another `useExisting` token. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='ExistingProvider'} + * {@example core/di/ts/provider_spec.ts region='ExistingProvider' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ export interface ExistingProvider extends ExistingSansProvider { /** - * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`). + * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`. */ provide: any; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; @@ -206,7 +196,8 @@ export interface ExistingProvider extends ExistingSansProvider { /** * Configures the `Injector` to return a value by invoking a `useFactory` function. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see `FactoryProvider` + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @publicApi */ @@ -218,7 +209,7 @@ export interface FactorySansProvider { useFactory: Function; /** - * A list of `token`s which need to be resolved by the injector. The list of values is then + * A list of `token`s to be resolved by the injector. The list of values is then * used as arguments to the `useFactory` function. */ deps?: any[]; @@ -226,22 +217,19 @@ export interface FactorySansProvider { /** * Configures the `Injector` to return a value by invoking a `useFactory` function. - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='FactoryProvider'} + * {@example core/di/ts/provider_spec.ts region='FactoryProvider' linenums="false"} * * Dependencies can also be marked as optional: * - * {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps'} + * {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ @@ -252,20 +240,15 @@ export interface FactoryProvider extends FactorySansProvider { provide: any; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; } /** - * Describes how the `Injector` should be configured in a static way (Without reflection). - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). - * - * @see `ValueProvider` - * @see `ExistingProvider` - * @see `FactoryProvider` + * Describes how the `Injector` should be configured as static (that is, without reflection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @publicApi */ @@ -283,9 +266,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi * * @usageNotes * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='TypeProvider'} + * {@example core/di/ts/provider_spec.ts region='TypeProvider' linenums="false"} * * @publicApi */ @@ -295,7 +276,7 @@ export interface TypeProvider extends Type {} * Configures the `Injector` to return a value by invoking a `useClass` function. * Base for `ClassProvider` decorator. * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @publicApi */ @@ -308,22 +289,19 @@ export interface ClassSansProvider { /** * Configures the `Injector` to return an instance of `useClass` for a token. - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * @see ["Dependency Injection Guide"](guide/dependency-injection). * * @usageNotes * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='ClassProvider'} + * {@example core/di/ts/provider_spec.ts region='ClassProvider' linenums="false"} * * Note that following two providers are not equal: * - * {@example core/di/ts/provider_spec.ts region='ClassProviderDifference'} + * {@example core/di/ts/provider_spec.ts region='ClassProviderDifference' linenums="false"} * * ### Multi-value example * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"} * * @publicApi */ @@ -334,7 +312,7 @@ export interface ClassProvider extends ClassSansProvider { provide: any; /** - * If true, then injector returns an array of instances. This is useful to allow multiple + * When true, injector returns an array of instances. This is useful to allow multiple * providers spread across many files to provide configuration information to a common token. */ multi?: boolean; @@ -342,11 +320,8 @@ export interface ClassProvider extends ClassSansProvider { /** * Describes how the `Injector` should be configured. + * @see ["Dependency Injection Guide"](guide/dependency-injection). * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). - * - * @see `TypeProvider` - * @see `ClassProvider` * @see `StaticProvider` * * @publicApi @@ -355,7 +330,7 @@ export type Provider = TypeProvider | ValueProvider | ClassProvider | Constructo ExistingProvider | FactoryProvider | any[]; /** - * Describes a function that is used to process provider list (for example in case of provider + * Describes a function that is used to process provider lists (such as provider * overrides). */ export type ProcessProvidersFunction = (providers: Provider[]) => Provider[]; diff --git a/packages/core/src/di/metadata.ts b/packages/core/src/di/metadata.ts index f5e55cfca1..4337e02697 100644 --- a/packages/core/src/di/metadata.ts +++ b/packages/core/src/di/metadata.ts @@ -17,7 +17,7 @@ import {makeParamDecorator} from '../util/decorators'; */ export interface InjectDecorator { /** - * A parameter decorator on a dependency parameter of a class constructor + * Parameter decorator on a dependency parameter of a class constructor * that specifies a custom provider of the dependency. * * Learn more in the ["Dependency Injection Guide"](guide/dependency-injection). @@ -30,7 +30,7 @@ export interface InjectDecorator { * parameter as the provider. * * + * region="InjectWithoutDecorator" linenums="false"> */ (token: any): any; new (token: any): Inject; @@ -64,7 +64,7 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any) */ export interface OptionalDecorator { /** - * A parameter decorator to be used on constructor parameters, + * Parameter decorator to be used on constructor parameters, * which marks the parameter as being an optional dependency. * The DI framework provides null if the dependency is not found. * @@ -77,7 +77,8 @@ export interface OptionalDecorator { * * The following code allows the possibility of a null result: * - * + * * */ (): any; @@ -106,7 +107,7 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional'); */ export interface SelfDecorator { /** - * A parameter decorator to be used on constructor parameters, + * Parameter decorator to be used on constructor parameters, * which tells the DI framework to start dependency resolution from the local injector. * * Resolution works upward through the injector hierarchy, so the children @@ -118,8 +119,9 @@ export interface SelfDecorator { * by the local injector when instantiating the class itself, but not * when instantiating a child. * - * - * + * + * * * @see `SkipSelf` * @see `Optional` @@ -152,7 +154,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self'); */ export interface SkipSelfDecorator { /** - * A parameter decorator to be used on constructor parameters, + * Parameter decorator to be used on constructor parameters, * which tells the DI framework to start dependency resolution from the parent injector. * Resolution works upward through the injector hierarchy, so the local injector * is not checked for a provider. @@ -162,7 +164,8 @@ export interface SkipSelfDecorator { * In the following example, the dependency can be resolved when * instantiating a child, but not when instantiating the class itself. * - * + * * * Learn more in the * [Dependency Injection guide](guide/dependency-injection-in-action#skip). @@ -197,7 +200,7 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf'); */ export interface HostDecorator { /** - * A parameter decorator on a view-provider parameter of a class constructor + * Parameter decorator on a view-provider parameter of a class constructor * that tells the DI framework to resolve the view by checking injectors of child * elements, and stop when reaching the host element of the current component. * @@ -208,7 +211,8 @@ export interface HostDecorator { * * The following shows use with the `@Optional` decorator, and allows for a null result. * - * + * */ (): any; new (): Host; @@ -237,7 +241,7 @@ export const Host: HostDecorator = makeParamDecorator('Host'); */ export interface AttributeDecorator { /** - * A parameter decorator for a directive constructor that designates + * Parameter decorator for a directive constructor that designates * a host-element attribute whose value is injected as a constant string literal. * * @usageNotes @@ -250,11 +254,11 @@ export interface AttributeDecorator { * * The following example uses the decorator to inject the string literal `text`. * - * {@example core/ts/metadata/metadata.ts region='attributeMetadata'} + * {@example core/ts/metadata/metadata.ts region='attributeMetadata' linenums="false"} * * ### Example as TypeScript Decorator * - * {@example core/ts/metadata/metadata.ts region='attributeFactory'} + * {@example core/ts/metadata/metadata.ts region='attributeFactory' linenums="false"} * */ (name: string): any; diff --git a/packages/core/src/event_emitter.ts b/packages/core/src/event_emitter.ts index f662fe4763..7c212c160b 100644 --- a/packages/core/src/event_emitter.ts +++ b/packages/core/src/event_emitter.ts @@ -21,7 +21,7 @@ import {Subject, Subscription} from 'rxjs'; * that create event emitters. When the title is clicked, the emitter * emits an open or close event to toggle the current visibility state. * - * ``` + * ```html * @Component({ * selector: 'zippy', * template: ` @@ -50,17 +50,10 @@ import {Subject, Subscription} from 'rxjs'; * Access the event object with the `$event` argument passed to the output event * handler: * - * ``` + * ```html * * ``` * - * ### Notes - * - * Uses Rx.Observable but provides an adapter to make it work as specified here: - * https://github.com/jhusain/observable-spec - * - * Once a reference implementation of the spec is available, switch to it. - * * @publicApi */ export class EventEmitter extends Subject { diff --git a/packages/core/src/linker/component_factory.ts b/packages/core/src/linker/component_factory.ts index 4ce743ca4a..7d43d397e8 100644 --- a/packages/core/src/linker/component_factory.ts +++ b/packages/core/src/linker/component_factory.ts @@ -49,7 +49,7 @@ export abstract class ComponentRef { abstract get changeDetectorRef(): ChangeDetectorRef; /** - * The component type. + * The type of this component (as created by a `ComponentFactory` class). */ abstract get componentType(): Type; @@ -68,6 +68,12 @@ export abstract class ComponentRef { } /** + * Base class for a factory that can create a component dynamically. + * Instantiate a factory for a given type of component with `resolveComponentFactory()`. + * Use the resulting `ComponentFactory.create()` method to create a component of that type. + * + * @see [Dynamic Components](guide/dynamic-component-loader) + * * @publicApi */ export abstract class ComponentFactory { @@ -76,7 +82,7 @@ export abstract class ComponentFactory { */ abstract get selector(): string; /** - * The component's type + * The type of component the factory will create. */ abstract get componentType(): Type; /** diff --git a/packages/core/src/linker/component_factory_resolver.ts b/packages/core/src/linker/component_factory_resolver.ts index 7d925672a5..90cdd073cf 100644 --- a/packages/core/src/linker/component_factory_resolver.ts +++ b/packages/core/src/linker/component_factory_resolver.ts @@ -34,10 +34,20 @@ class _NullComponentFactoryResolver implements ComponentFactoryResolver { } /** + * A simple registry that maps `Components` to generated `ComponentFactory` classes + * that can be used to create instances of components. + * Use to obtain the factory for a given component type, + * then use the factory's `create()` method to create a component of that type. + * + * @see [Dynamic Components](guide/dynamic-component-loader) * @publicApi */ export abstract class ComponentFactoryResolver { static NULL: ComponentFactoryResolver = new _NullComponentFactoryResolver(); + /** + * Retrieves the factory object that creates a component of the given type. + * @param component The component type. + */ abstract resolveComponentFactory(component: Type): ComponentFactory; } diff --git a/packages/core/src/metadata/di.ts b/packages/core/src/metadata/di.ts index eec9b89bc6..cf5b6bc108 100644 --- a/packages/core/src/metadata/di.ts +++ b/packages/core/src/metadata/di.ts @@ -60,7 +60,6 @@ export interface AttributeDecorator { * The directive can inject constant string literals of host element attributes. * * @usageNotes - * ### Example * * Suppose we have an `` element and want to know its `type`. * @@ -70,7 +69,8 @@ export interface AttributeDecorator { * * A decorator can inject string literal `text` as in the following example. * - * {@example core/ts/metadata/metadata.ts region='attributeMetadata'} + * {@example core/ts/metadata/metadata.ts region='attributeMetadata' + * linenums="false"} * * @publicApi */ @@ -125,33 +125,34 @@ export abstract class Query {} */ export interface ContentChildrenDecorator { /** - * Configures a content query. + * Parameter decorator that configures a content query. * - * You can use ContentChildren to get the `QueryList` of elements or directives from the - * content DOM. Any time a child element is added, removed, or moved, the query list will be + * Use to get the `QueryList` of elements or directives from the content DOM. + * Any time a child element is added, removed, or moved, the query list will be * updated, and the changes observable of the query list will emit a new value. * * Content queries are set before the `ngAfterContentInit` callback is called. * * **Metadata Properties**: * - * * **selector** - the directive type or the name used for querying. - * * **descendants** - include only direct children or all descendants. - * * **read** - read a different token from the queried elements. + * * **selector** - The directive type or the name used for querying. + * * **descendants** - True to include all descendants, otherwise include only direct children. + * * **read** - True to read a different token from the queried elements. * * @usageNotes - * ### Basic Example * * Here is a simple demonstration of how the `ContentChildren` decorator can be used. * - * {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'} + * {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo' + * linenums="false"} * - * ### Tab-pane Example + * ### Tab-pane example * * Here is a slightly more realistic example that shows how `ContentChildren` decorators * can be used to implement a tab pane component. * - * {@example core/di/ts/contentChildren/content_children_example.ts region='Component'} + * {@example core/di/ts/contentChildren/content_children_example.ts region='Component' + * linenums="false"} * * @Annotation */ @@ -188,33 +189,35 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator( */ export interface ContentChildDecorator { /** - * Configures a content query. + * Parameter decorator that configures a content query. * - * You can use ContentChild to get the first element or the directive matching the selector from - * the content DOM. If the content DOM changes, and a new child matches the selector, + * Use to get the first element or the directive matching the selector from the content DOM. + * If the content DOM changes, and a new child matches the selector, * the property will be updated. * * Content queries are set before the `ngAfterContentInit` callback is called. * * **Metadata Properties**: * - * * **selector** - the directive type or the name used for querying. - * * **read** - read a different token from the queried element. - * * **static** - whether or not to resolve query results before change detection runs (i.e. - * return static results only). If this option is not provided, the compiler will fall back - * to its default behavior, which is to use query results to determine the timing of query - * resolution. If any query results are inside a nested view (e.g. *ngIf), the query will be - * resolved after change detection runs. Otherwise, it will be resolved before change detection + * * **selector** - The directive type or the name used for querying. + * * **read** - True to read a different token from the queried element. + * * **static** - True to resolve query results before change detection runs, + * false to resolve after change detection. + * + * When `static` is not provided, uses the query results to determine the timing of query + * resolution. If any query results are inside a nested view (such as `*ngIf`), the query is + * resolved after change detection runs. Otherwise, it is resolved before change detection * runs. * * @usageNotes - * ### Example * - * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'} + * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo' + * linenums="false"} * * ### Example * - * {@example core/di/ts/contentChild/content_child_example.ts region='Component'} + * {@example core/di/ts/contentChild/content_child_example.ts region='Component' + * linenums="false"} * * @Annotation */ @@ -251,28 +254,28 @@ export const ContentChild: ContentChildDecorator = makePropDecorator( */ export interface ViewChildrenDecorator { /** - * Configures a view query. + * Parameter decorator that configures a view query. * - * You can use ViewChildren to get the `QueryList` of elements or directives from the - * view DOM. Any time a child element is added, removed, or moved, the query list will be updated, + * Use to get the `QueryList` of elements or directives from the view DOM. + * Any time a child element is added, removed, or moved, the query list will be updated, * and the changes observable of the query list will emit a new value. * * View queries are set before the `ngAfterViewInit` callback is called. * * **Metadata Properties**: * - * * **selector** - the directive type or the name used for querying. - * * **read** - read a different token from the queried elements. + * * **selector** - The directive type or the name used for querying. + * * **read** - True to read a different token from the queried elements. * * @usageNotes * - * ### Example + * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo' + * linenums="false"} * - * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'} + * ### Another example * - * ### Example - * - * {@example core/di/ts/viewChildren/view_children_example.ts region='Component'} + * {@example core/di/ts/viewChildren/view_children_example.ts region='Component' + * linenums="false"} * * @Annotation */ @@ -316,37 +319,40 @@ export interface ViewChildDecorator { * * **Metadata Properties**: * - * * **selector** - the directive type or the name used for querying. - * * **read** - read a different token from the queried elements. - * * **static** - whether or not to resolve query results before change detection runs (i.e. - * return static results only). If this option is not provided, the compiler will fall back - * to its default behavior, which is to use query results to determine the timing of query - * resolution. If any query results are inside a nested view (e.g. *ngIf), the query will be - * resolved after change detection runs. Otherwise, it will be resolved before change detection + * * **selector** - The directive type or the name used for querying. + * * **read** - True to read a different token from the queried elements. + * * **static** - True to resolve query results before change detection runs + * + * When `static` is not provided, uses query results to determine the timing of query + * resolution. If any query results are inside a nested view (such as `*ngIf`), the query is + * resolved after change detection runs. Otherwise, it is resolved before change detection * runs. * - * Supported selectors include: - * * any class with the `@Component` or `@Directive` decorator - * * a template reference variable as a string (e.g. query `` + * The following selectors are supported. + * * Any class with the `@Component` or `@Directive` decorator + * * A template reference variable as a string (e.g. query `` * with `@ViewChild('cmp')`) - * * any provider defined in the child component tree of the current component (e.g. + * * Any provider defined in the child component tree of the current component (e.g. * `@ViewChild(SomeService) someService: SomeService`) - * * any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal: + * * Any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal: * any`) - * * a `TemplateRef` (e.g. query `` with `@ViewChild(TemplateRef) + * * A `TemplateRef` (e.g. query `` with `@ViewChild(TemplateRef) * template;`) * * @usageNotes * - * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} + * {@example core/di/ts/viewChild/view_child_example.ts region='Component' + * linenums="false"} * - * ### Example + * ### Example 2 * - * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'} + * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo' + * linenums="false"} * - * ### Example + * ### Example 3 * - * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} + * {@example core/di/ts/viewChild/view_child_example.ts region='Component' + * linenums="false"} * * @Annotation */ diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index 1177981427..ffd21e11f1 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -24,8 +24,9 @@ import {ViewEncapsulation} from './view'; */ export interface DirectiveDecorator { /** - * Marks a class as an Angular directive. You can define your own - * directives to attach custom behavior to elements in the DOM. + * Decorator that marks a class as an Angular directive. + * You can define your own directives to attach custom behavior to elements in the DOM. + * * The options provide configuration metadata that determines * how the directive should be processed, instantiated and used at * runtime. @@ -37,7 +38,7 @@ export interface DirectiveDecorator { * @usageNotes * To define a directive, mark the class with the decorator and provide metadata. * - * ``` + * ```ts * import {Directive} from '@angular/core'; * * @Directive({ @@ -58,7 +59,7 @@ export interface DirectiveDecorator { * a directive imported from another module. * List the directive class in the `declarations` field of an NgModule. * - * ``` + * ```ts * declarations: [ * AppComponent, * MyDirective @@ -122,9 +123,8 @@ export interface Directive { * - `bindingProperty` specifies the DOM property where the value is read from. * * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`. - * @usageNotes * - * ### Example + * @usageNotes * * The following example creates a component with two data-bound properties. * @@ -160,8 +160,6 @@ export interface Directive { * * @usageNotes * - * ### Example - * * ```typescript * @Component({ * selector: 'child-dir', @@ -202,9 +200,7 @@ export interface Directive { * * @usageNotes * - * ### Simple Example - * - * ``` + * ```ts * @Directive({ * selector: 'child-dir', * exportAs: 'child' @@ -231,12 +227,10 @@ export interface Directive { * * @usageNotes * - * ### Example - * * The following example shows how queries are defined * and when their results are available in lifecycle hooks: * - * ``` + * ```ts * @Component({ * selector: 'someDir', * queries: { @@ -338,7 +332,8 @@ export interface ComponentDecorator { * The following example creates a component with two data-bound properties, * specified by the `inputs` value. * - * + * * * * @@ -347,14 +342,15 @@ export interface ComponentDecorator { * The following example shows two event emitters that emit on an interval. One * emits an output every second, while the other emits every five seconds. * - * {@example core/ts/metadata/directives.ts region='component-output-interval'} + * {@example core/ts/metadata/directives.ts region='component-output-interval + * linenums="false"} * * ### Injecting a class with a view provider * * The following simple example injects a class into a component * using the view provider specified in component metadata: * - * ``` + * ```ts * class Greeter { * greet(name:string) { * return 'Hello ' + name + '!'; @@ -395,13 +391,13 @@ export interface ComponentDecorator { * * Trims all whitespaces at the beginning and the end of a template. * * Removes whitespace-only text nodes. For example, * - * ``` + * ```html * * ``` * * becomes: * - * ``` + * ```html * * ``` * @@ -844,9 +840,10 @@ export interface HostListener { } /** - * Binds a DOM event to a host listener and supplies configuration metadata. + * Decorator that binds a DOM event to a host listener and supplies configuration metadata. * Angular invokes the supplied handler method when the host element emits the specified event, * and updates the bound element with the result. + * * If the handler method returns false, applies `preventDefault` on the bound element. * * @usageNotes @@ -854,7 +851,7 @@ export interface HostListener { * The following example declares a directive * that attaches a click listener to a button and counts clicks. * - * ``` + * ```ts * @Directive({selector: 'button[counting]'}) * class CountClicks { * numberOfClicks = 0; diff --git a/packages/core/src/util/decorators.ts b/packages/core/src/util/decorators.ts index 907f4b9695..f19c4e9852 100644 --- a/packages/core/src/util/decorators.ts +++ b/packages/core/src/util/decorators.ts @@ -9,11 +9,8 @@ import {Type} from '../interface/type'; /** - * An interface implemented by all Angular type decorators, which allows them to be used as ES7 - * decorators as well as - * Angular DSL syntax. - * - * ES7 syntax: + * An interface implemented by all Angular type decorators, which allows them to be used as + * decorators as well as Angular syntax. * * ``` * @ng.Component({...}) @@ -24,7 +21,7 @@ import {Type} from '../interface/type'; */ export interface TypeDecorator { /** - * Invoke as ES7 decorator. + * Invoke as decorator. */ >(type: T): T; diff --git a/packages/examples/core/di/ts/contentChild/content_child_example.ts b/packages/examples/core/di/ts/contentChild/content_child_example.ts index 28928cc4ad..ca58b6a23c 100644 --- a/packages/examples/core/di/ts/contentChild/content_child_example.ts +++ b/packages/examples/core/di/ts/contentChild/content_child_example.ts @@ -11,18 +11,16 @@ import {Component, ContentChild, Directive, Input} from '@angular/core'; @Directive({selector: 'pane'}) export class Pane { - // TODO(issue/24571): remove '!'. @Input() id !: string; } @Component({ selector: 'tab', template: ` -
pane: {{pane?.id}}
+
pane: {{pane?.id}}
` }) export class Tab { - // TODO(issue/24571): remove '!'. @ContentChild(Pane, {static: false}) pane !: Pane; } @@ -33,7 +31,7 @@ export class Tab { - + `, }) diff --git a/packages/examples/core/di/ts/contentChildren/content_children_example.ts b/packages/examples/core/di/ts/contentChildren/content_children_example.ts index b0befe6709..99e981b87b 100644 --- a/packages/examples/core/di/ts/contentChildren/content_children_example.ts +++ b/packages/examples/core/di/ts/contentChildren/content_children_example.ts @@ -11,14 +11,13 @@ import {Component, ContentChildren, Directive, Input, QueryList} from '@angular/ @Directive({selector: 'pane'}) export class Pane { - // TODO(issue/24571): remove '!'. @Input() id !: string; } @Component({ selector: 'tab', template: ` -
Top level panes: {{serializedPanes}}
+
Top level panes: {{serializedPanes}}
Arbitrary nested panes: {{serializedNestedPanes}}
` }) @@ -47,7 +46,7 @@ export class Tab { - + `, }) diff --git a/packages/examples/core/di/ts/contentChildren/content_children_howto.ts b/packages/examples/core/di/ts/contentChildren/content_children_howto.ts index 776ed57daf..32c5b4b81c 100644 --- a/packages/examples/core/di/ts/contentChildren/content_children_howto.ts +++ b/packages/examples/core/di/ts/contentChildren/content_children_howto.ts @@ -15,7 +15,6 @@ class ChildDirective { @Directive({selector: 'someDir'}) class SomeDir implements AfterContentInit { - // TODO(issue/24571): remove '!'. @ContentChildren(ChildDirective) contentChildren !: QueryList; ngAfterContentInit() { diff --git a/packages/examples/core/di/ts/provider_spec.ts b/packages/examples/core/di/ts/provider_spec.ts index 087a376759..b08423e55c 100644 --- a/packages/examples/core/di/ts/provider_spec.ts +++ b/packages/examples/core/di/ts/provider_spec.ts @@ -55,9 +55,7 @@ import {Injectable, InjectionToken, Injector, Optional, ReflectiveInjector} from describe('ClassProvider', () => { it('works', () => { // #docregion ClassProvider - abstract class Shape { // TODO(issue/24571): remove '!'. - name !: string; - } + abstract class Shape { name !: string; } class Square extends Shape { name = 'square'; @@ -94,9 +92,7 @@ import {Injectable, InjectionToken, Injector, Optional, ReflectiveInjector} from describe('StaticClassProvider', () => { it('works', () => { // #docregion StaticClassProvider - abstract class Shape { // TODO(issue/24571): remove '!'. - name !: string; - } + abstract class Shape { name !: string; } class Square extends Shape { name = 'square'; diff --git a/packages/examples/core/di/ts/viewChild/view_child_example.ts b/packages/examples/core/di/ts/viewChild/view_child_example.ts index c624cf87e3..49a4fdec86 100644 --- a/packages/examples/core/di/ts/viewChild/view_child_example.ts +++ b/packages/examples/core/di/ts/viewChild/view_child_example.ts @@ -11,7 +11,6 @@ import {Component, Directive, Input, ViewChild} from '@angular/core'; @Directive({selector: 'pane'}) export class Pane { - // TODO(issue/24571): remove '!'. @Input() id !: string; } @@ -20,10 +19,10 @@ export class Pane { template: ` - + - -
Selected: {{selectedPane}}
+ +
Selected: {{selectedPane}}
`, }) export class ViewChildComp { diff --git a/packages/examples/core/di/ts/viewChild/view_child_howto.ts b/packages/examples/core/di/ts/viewChild/view_child_howto.ts index f3d74ac953..0547525408 100644 --- a/packages/examples/core/di/ts/viewChild/view_child_howto.ts +++ b/packages/examples/core/di/ts/viewChild/view_child_howto.ts @@ -15,7 +15,6 @@ class ChildDirective { @Component({selector: 'someCmp', templateUrl: 'someCmp.html'}) class SomeCmp implements AfterViewInit { - // TODO(issue/24571): remove '!'. @ViewChild(ChildDirective, {static: false}) child !: ChildDirective; ngAfterViewInit() { diff --git a/packages/examples/core/di/ts/viewChildren/view_children_example.ts b/packages/examples/core/di/ts/viewChildren/view_children_example.ts index bd5e95233b..f89bf47524 100644 --- a/packages/examples/core/di/ts/viewChildren/view_children_example.ts +++ b/packages/examples/core/di/ts/viewChildren/view_children_example.ts @@ -11,7 +11,6 @@ import {AfterViewInit, Component, Directive, Input, QueryList, ViewChildren} fro @Directive({selector: 'pane'}) export class Pane { - // TODO(issue/24571): remove '!'. @Input() id !: string; } @@ -21,14 +20,13 @@ export class Pane { - + - -
panes: {{serializedPanes}}
+ +
panes: {{serializedPanes}}
`, }) export class ViewChildrenComp implements AfterViewInit { - // TODO(issue/24571): remove '!'. @ViewChildren(Pane) panes !: QueryList; serializedPanes: string = ''; diff --git a/packages/examples/core/di/ts/viewChildren/view_children_howto.ts b/packages/examples/core/di/ts/viewChildren/view_children_howto.ts index 7675788391..4d4273e5ba 100644 --- a/packages/examples/core/di/ts/viewChildren/view_children_howto.ts +++ b/packages/examples/core/di/ts/viewChildren/view_children_howto.ts @@ -15,7 +15,6 @@ class ChildDirective { @Component({selector: 'someCmp', templateUrl: 'someCmp.html'}) class SomeCmp implements AfterViewInit { - // TODO(issue/24571): remove '!'. @ViewChildren(ChildDirective) viewChildren !: QueryList; ngAfterViewInit() {