From e6516b0229398430fd11d0d433e8c3712b182b3b Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 18 May 2018 16:13:00 +0100 Subject: [PATCH] docs: fix invalid headings (#24000) PR Close #24000 --- packages/animations/src/animation_metadata.ts | 4 +- packages/core/src/application_ref.ts | 15 +- .../change_detection/change_detector_ref.ts | 6 +- .../differs/iterable_differs.ts | 5 +- .../differs/keyvalue_differs.ts | 5 +- .../src/change_detection/pipe_transform.ts | 5 +- packages/core/src/di/forward_ref.ts | 10 +- packages/core/src/di/injectable.ts | 20 +- packages/core/src/di/injection_token.ts | 12 +- packages/core/src/di/injector.ts | 16 +- packages/core/src/di/metadata.ts | 89 +-------- packages/core/src/di/provider.ts | 180 ++++-------------- packages/core/src/di/reflective_errors.ts | 7 + packages/core/src/di/reflective_injector.ts | 26 ++- packages/core/src/di/reflective_provider.ts | 19 +- packages/core/src/error_handler.ts | 5 +- packages/core/src/event_emitter.ts | 3 + packages/core/src/i18n/tokens.ts | 4 + packages/core/src/linker/query_list.ts | 2 +- packages/core/src/linker/view_ref.ts | 15 +- packages/core/src/metadata/di.ts | 108 +++++------ packages/core/src/metadata/directives.ts | 155 ++++++--------- packages/core/src/render3/view_ref.ts | 4 + packages/core/src/zone/ng_zone.ts | 1 + packages/core/testing/src/fake_async.ts | 6 +- .../core/testing/src/fake_async_fallback.ts | 6 +- 26 files changed, 255 insertions(+), 473 deletions(-) diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts index c2c4afad43..a46524c412 100755 --- a/packages/animations/src/animation_metadata.ts +++ b/packages/animations/src/animation_metadata.ts @@ -42,8 +42,8 @@ export declare type AnimateTimings = { * @description Options that control animation styling and timing. * The following animation functions accept `AnimationOptions` data: * - * - `transition` - * - `sequence` + * - `transition()` + * - `sequence()` * - `group()` * - `query()` * - `animation()` diff --git a/packages/core/src/application_ref.ts b/packages/core/src/application_ref.ts index ce30069931..2f3beb8622 100644 --- a/packages/core/src/application_ref.ts +++ b/packages/core/src/application_ref.ts @@ -180,8 +180,6 @@ export interface BootstrapOptions { * * A page's platform is initialized implicitly when a platform is created via a platform factory * (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function. - * - * */ @Injectable() export class PlatformRef { @@ -196,7 +194,8 @@ export class PlatformRef { * Creates an instance of an `@NgModule` for the given platform * for offline compilation. * - * ## Simple Example + * @usageNotes + * ### Simple Example * * ```typescript * my_module.ts: @@ -252,7 +251,8 @@ export class PlatformRef { /** * Creates an instance of an `@NgModule` for a given platform using the given runtime compiler. * - * ## Simple Example + * @usageNotes + * ### Simple Example * * ```typescript * @NgModule({ @@ -358,8 +358,6 @@ function optionsReducer(dst: any, objs: T | T[]): T { /** * A reference to an Angular application running on a page. - * - * */ @Injectable() export class ApplicationRef { @@ -448,14 +446,15 @@ export class ApplicationRef { /** * Bootstrap a new component at the root level of the application. * + * @usageNotes * ### Bootstrap process * * When bootstrapping a new root component into an application, Angular mounts the - * specified application component onto DOM elements identified by the [componentType]'s + * specified application component onto DOM elements identified by the componentType's * selector and kicks off automatic change detection to finish initializing the component. * * Optionally, a component can be mounted onto a DOM element that does not match the - * [componentType]'s selector. + * componentType's selector. * * ### Example * {@example core/ts/platform/platform.ts region='longform'} diff --git a/packages/core/src/change_detection/change_detector_ref.ts b/packages/core/src/change_detection/change_detector_ref.ts index 743f5f66ae..2c50ff96aa 100644 --- a/packages/core/src/change_detection/change_detector_ref.ts +++ b/packages/core/src/change_detection/change_detector_ref.ts @@ -16,6 +16,7 @@ export abstract class ChangeDetectorRef { * * * + * @usageNotes * ### Example * * ```typescript @@ -50,6 +51,7 @@ export abstract class ChangeDetectorRef { * * * + * @usageNotes * ### Example * * The following example defines a component with a large list of readonly data. @@ -102,9 +104,8 @@ export abstract class ChangeDetectorRef { * * * - * ### Example + * @usageNotes * - * The following example defines a component with a large list of readonly data. * Imagine, the data changes constantly, many times per second. For performance reasons, * we want to check and update the list every five seconds. * @@ -131,6 +132,7 @@ export abstract class ChangeDetectorRef { * * * + * @usageNotes * ### Example * * The following example creates a component displaying `live` data. The component will detach diff --git a/packages/core/src/change_detection/differs/iterable_differs.ts b/packages/core/src/change_detection/differs/iterable_differs.ts index c631f42aa0..1c7ede1213 100644 --- a/packages/core/src/change_detection/differs/iterable_differs.ts +++ b/packages/core/src/change_detection/differs/iterable_differs.ts @@ -162,12 +162,13 @@ export class IterableDiffers { * inherited {@link IterableDiffers} instance with the provided factories and return a new * {@link IterableDiffers} instance. * + * @usageNotes + * ### Example + * * The following example shows how to extend an existing list of factories, * which will only be applied to the injector for this component and its children. * This step is all that's required to make a new {@link IterableDiffer} available. * - * ### Example - * * ``` * @Component({ * viewProviders: [ diff --git a/packages/core/src/change_detection/differs/keyvalue_differs.ts b/packages/core/src/change_detection/differs/keyvalue_differs.ts index 6a9807c587..47dcaf81b6 100644 --- a/packages/core/src/change_detection/differs/keyvalue_differs.ts +++ b/packages/core/src/change_detection/differs/keyvalue_differs.ts @@ -135,12 +135,13 @@ export class KeyValueDiffers { * inherited {@link KeyValueDiffers} instance with the provided factories and return a new * {@link KeyValueDiffers} instance. * + * @usageNotes + * ### Example + * * The following example shows how to extend an existing list of factories, * which will only be applied to the injector for this component and its children. * This step is all that's required to make a new {@link KeyValueDiffer} available. * - * ### Example - * * ``` * @Component({ * viewProviders: [ diff --git a/packages/core/src/change_detection/pipe_transform.ts b/packages/core/src/change_detection/pipe_transform.ts index e835d7f610..740581d6ac 100644 --- a/packages/core/src/change_detection/pipe_transform.ts +++ b/packages/core/src/change_detection/pipe_transform.ts @@ -12,10 +12,7 @@ * 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. * - * ## Syntax - * - * `value | pipeName[:arg0[:arg1...]]` - * + * @usageNotes * ### Example * * The `RepeatPipe` below repeats the value as many times as indicated by the first argument: diff --git a/packages/core/src/di/forward_ref.ts b/packages/core/src/di/forward_ref.ts index 6837df128c..3d9b7f27aa 100644 --- a/packages/core/src/di/forward_ref.ts +++ b/packages/core/src/di/forward_ref.ts @@ -14,6 +14,7 @@ import {stringify} from '../util'; /** * An interface that a function passed into {@link forwardRef} has to implement. * + * @usageNotes * ### Example * * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref_fn'} @@ -25,10 +26,10 @@ export interface ForwardRefFn { (): any; } * Allows to refer to references which are not yet defined. * * For instance, `forwardRef` is used when the `token` which we need to refer to for the purposes of - * DI is declared, - * but not yet defined. It is also used when the `token` which we use when creating a query is not - * yet defined. + * DI is declared, but not yet defined. It is also used when the `token` which we use when creating + * a query is not yet defined. * + * @usageNotes * ### Example * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref'} * @experimental @@ -44,11 +45,12 @@ export function forwardRef(forwardRefFn: ForwardRefFn): Type { * * Acts as the identity function when given a non-forward-ref value. * + * @usageNotes * ### Example * * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='resolve_forward_ref'} * - * See: {@link forwardRef} + * @see `forwardRef` * @experimental */ export function resolveForwardRef(type: any): any { diff --git a/packages/core/src/di/injectable.ts b/packages/core/src/di/injectable.ts index 581f1d0b6e..d1dacf1033 100644 --- a/packages/core/src/di/injectable.ts +++ b/packages/core/src/di/injectable.ts @@ -30,32 +30,23 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider | /** * Type of the Injectable decorator / constructor function. - * - * */ export interface InjectableDecorator { /** + * A marker metadata that marks a class as available to `Injector` for creation. + * + * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * * @usageNotes - * ``` - * @Injectable() - * class Car {} - * ``` - * - * @description - * A marker metadata that marks a class as available to {@link Injector} for creation. - * - * For more details, see the ["Dependency Injection Guide"(guide/dependency-injection). - * * ### Example * * {@example core/di/ts/metadata_spec.ts region='Injectable'} * - * {@link Injector} will throw an error when trying to instantiate a class that + * `Injector` will throw an error when trying to instantiate a class that * does not have `@Injectable` marker, as shown in the example below. * * {@example core/di/ts/metadata_spec.ts region='InjectableThrows'} * - * */ (): any; (options?: {providedIn: Type| 'root' | null}&InjectableProvider): any; @@ -125,7 +116,6 @@ function preR3InjectableCompile( /** * Injectable decorator and metadata. * -* * @Annotation */ export const Injectable: InjectableDecorator = makeDecorator( diff --git a/packages/core/src/di/injection_token.ts b/packages/core/src/di/injection_token.ts index 364e0b9c7b..f33d3a5d48 100644 --- a/packages/core/src/di/injection_token.ts +++ b/packages/core/src/di/injection_token.ts @@ -36,16 +36,14 @@ import {InjectableDef, defineInjectable} from './defs'; * overrides the above behavior and marks the token as belonging to a particular `@NgModule`. As * mentioned above, `'root'` is the default value for `providedIn`. * - * ### Example - * - * #### Tree-shakeable InjectionToken - * - * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'} - * - * #### Plain InjectionToken + * @usageNotes + * ### Basic Example * * {@example core/di/ts/injector_spec.ts region='InjectionToken'} * + * ### Tree-shakeable Example + * + * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'} * */ export class InjectionToken { diff --git a/packages/core/src/di/injector.ts b/packages/core/src/di/injector.ts index a3d02e1018..712ded66fa 100644 --- a/packages/core/src/di/injector.ts +++ b/packages/core/src/di/injector.ts @@ -43,23 +43,17 @@ export class NullInjector implements Injector { } /** - * @usageNotes - * ``` - * const injector: Injector = ...; - * injector.get(...); - * ``` - * - * @description - * * Concrete injectors implement this interface. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/injector_spec.ts region='Injector'} * * `Injector` returns itself when given `Injector` as a token: + * * {@example core/di/ts/injector_spec.ts region='injectInjector'} * * @@ -92,6 +86,7 @@ export abstract class Injector { /** * Create a new Injector which is configure using `StaticProvider`s. * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'} @@ -450,7 +445,10 @@ export function setCurrentInjector(injector: Injector | null | undefined): Injec * Injects a token from the currently active injector. * * This function must be used in the context of a factory function such as one defined for an - * `InjectionToken`, and will throw an error if not called from such a context. For example: + * `InjectionToken`, and will throw an error if not called from such a context. + * + * @usageNotes + * ### Example * * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'} * diff --git a/packages/core/src/di/metadata.ts b/packages/core/src/di/metadata.ts index 32ec55cbfd..ac10a47402 100644 --- a/packages/core/src/di/metadata.ts +++ b/packages/core/src/di/metadata.ts @@ -15,36 +15,24 @@ import {EMPTY_ARRAY} from '../view/util'; /** * Type of the Inject decorator / constructor function. - * - * */ export interface InjectDecorator { /** - * @usageNotes - * ``` - * @Injectable() - * class Car { - * constructor(@Inject("MyEngine") public engine:Engine) {} - * } - * ``` - * - * @description * A parameter decorator that specifies a dependency. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/metadata_spec.ts region='Inject'} * - * When `@Inject()` is not present, {@link Injector} will use the type annotation of the + * When `@Inject()` is not present, `Injector` will use the type annotation of the * parameter. * * ### Example * * {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'} - * - * */ (token: any): any; new (token: any): Inject; @@ -52,15 +40,12 @@ export interface InjectDecorator { /** * Type of the Inject metadata. - * - * */ export interface Inject { token: any; } /** * Inject decorator and metadata. * - * * @Annotation */ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any) => ({token})); @@ -68,30 +53,18 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any) /** * Type of the Optional decorator / constructor function. - * - * */ export interface OptionalDecorator { /** - * @usageNotes - * ``` - * @Injectable() - * class Car { - * constructor(@Optional() public engine:Engine) {} - * } - * ``` - * - * @description * A parameter metadata that marks a dependency as optional. - * {@link Injector} provides `null` if the dependency is not found. + * `Injector` provides `null` if the dependency is not found. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/metadata_spec.ts region='Optional'} - * - * */ (): any; new (): Optional; @@ -99,44 +72,29 @@ export interface OptionalDecorator { /** * Type of the Optional metadata. - * - * */ export interface Optional {} /** * Optional decorator and metadata. * - * * @Annotation */ export const Optional: OptionalDecorator = makeParamDecorator('Optional'); /** * Type of the Self decorator / constructor function. - * - * */ export interface SelfDecorator { /** - * @usageNotes - * ``` - * @Injectable() - * class Car { - * constructor(@Self() public engine:Engine) {} - * } - * ``` - * - * @description - * Specifies that an {@link Injector} should retrieve a dependency only from itself. + * Specifies that an `Injector` should retrieve a dependency only from itself. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/metadata_spec.ts region='Self'} - * - * */ (): any; new (): Self; @@ -144,15 +102,12 @@ export interface SelfDecorator { /** * Type of the Self metadata. - * - * */ export interface Self {} /** * Self decorator and metadata. * - * * @Annotation */ export const Self: SelfDecorator = makeParamDecorator('Self'); @@ -160,29 +115,17 @@ export const Self: SelfDecorator = makeParamDecorator('Self'); /** * Type of the SkipSelf decorator / constructor function. - * - * */ export interface SkipSelfDecorator { /** - * @usageNotes - * ``` - * @Injectable() - * class Car { - * constructor(@SkipSelf() public engine:Engine) {} - * } - * ``` - * - * @description * Specifies that the dependency resolution should start from the parent injector. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/metadata_spec.ts region='SkipSelf'} - * - * */ (): any; new (): SkipSelf; @@ -198,37 +141,24 @@ export interface SkipSelf {} /** * SkipSelf decorator and metadata. * - * * @Annotation */ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf'); /** * Type of the Host decorator / constructor function. - * - * */ export interface HostDecorator { /** - * @usageNotes - * ``` - * @Injectable() - * class Car { - * constructor(@Host() public engine:Engine) {} - * } - * ``` - * - * @description * Specifies that an injector should retrieve a dependency from any injector until * reaching the host element of the current component. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/metadata_spec.ts region='Host'} - * - * */ (): any; new (): Host; @@ -236,15 +166,12 @@ export interface HostDecorator { /** * Type of the Host metadata. - * - * */ export interface Host {} /** * Host decorator and metadata. * - * * @Annotation */ export const Host: HostDecorator = makeParamDecorator('Host'); diff --git a/packages/core/src/di/provider.ts b/packages/core/src/di/provider.ts index bb956dc81b..635af80b6c 100644 --- a/packages/core/src/di/provider.ts +++ b/packages/core/src/di/provider.ts @@ -9,17 +9,11 @@ import {Type} from '../type'; /** - * @usageNotes - * ``` - * @Injectable(SomeModule, {useValue: 'someValue'}) - * class SomeClass {} - * ``` - * - * @description * Configures the `Injector` to return a value for a token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ValueSansProvider'} @@ -34,21 +28,18 @@ export interface ValueSansProvider { } /** - * @usageNotes - * ``` - * const provider: ValueProvider = {provide: 'someToken', useValue: 'someValue'}; - * ``` - * - * @description * Configures the `Injector` to return a value for a token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ValueProvider'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface ValueProvider extends ValueSansProvider { /** @@ -59,26 +50,16 @@ export interface ValueProvider extends ValueSansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** - * @usageNotes - * ``` - * @Injectable(SomeModule, {useClass: MyService, deps: []}) - * class MyService {} - * ``` - * - * @description * Configures the `Injector` to return an instance of `useClass` for a token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='StaticClassSansProvider'} @@ -100,27 +81,22 @@ export interface StaticClassSansProvider { } /** - * @usageNotes - * ``` - * @Injectable() - * class MyService {} - * - * const provider: ClassProvider = {provide: 'someToken', useClass: MyService, deps: []}; - * ``` - * - * @description * Configures the `Injector` to return an instance of `useClass` for a token. * * For more details, see the ["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'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface StaticClassProvider extends StaticClassSansProvider { /** @@ -131,26 +107,23 @@ export interface StaticClassProvider extends StaticClassSansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** + * Configures the `Injector` to return an instance of a token. + * + * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). + * * @usageNotes + * ### Example + * * ``` * @Injectable(SomeModule, {deps: []}) * class MyService {} * ``` * - * @description - * Configures the `Injector` to return an instance of a token. - * - * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). - * * @experimental */ export interface ConstructorSansProvider { @@ -162,24 +135,18 @@ export interface ConstructorSansProvider { } /** - * @usageNotes - * ``` - * @Injectable() - * class MyService {} - * - * const provider: ClassProvider = {provide: MyClass, deps: []}; - * ``` - * - * @description * Configures the `Injector` to return an instance of a token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface ConstructorProvider extends ConstructorSansProvider { /** @@ -190,31 +157,19 @@ export interface ConstructorProvider extends ConstructorSansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** - * @usageNotes - * ``` - * @Injectable(SomeModule, {useExisting: 'someOtherToken'}) - * class SomeClass {} - * ``` - * - * @description * Configures the `Injector` to return a value of another `useExisting` token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ExistingSansProvider'} - * - * */ export interface ExistingSansProvider { /** @@ -224,21 +179,18 @@ export interface ExistingSansProvider { } /** - * @usageNotes - * ``` - * const provider: ExistingProvider = {provide: 'someToken', useExisting: 'someOtherToken'}; - * ``` - * - * @description * Configures the `Injector` to return a value of another `useExisting` token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ExistingProvider'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface ExistingProvider extends ExistingSansProvider { /** @@ -249,34 +201,22 @@ export interface ExistingProvider extends ExistingSansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** - * @usageNotes - * ``` - * function serviceFactory() { ... } - * - * @Injectable(SomeModule, {useFactory: serviceFactory, deps: []}) - * class SomeClass {} - * ``` - * - * @description * Configures the `Injector` to return a value by invoking a `useFactory` function. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='FactorySansProvider'} * * @experimental - */ + */ export interface FactorySansProvider { /** * A function to invoke to create a value for this `token`. The function is invoked with @@ -292,26 +232,22 @@ export interface FactorySansProvider { } /** - * @usageNotes - * ``` - * function serviceFactory() { ... } - * - * const provider: FactoryProvider = {provide: 'someToken', useFactory: serviceFactory, deps: []}; - * ``` - * - * @description * Configures the `Injector` to return a value by invoking a `useFactory` function. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='FactoryProvider'} * * Dependencies can also be marked as optional: + * * {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface FactoryProvider extends FactorySansProvider { /** @@ -322,39 +258,24 @@ export interface FactoryProvider extends FactorySansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** - * @usageNotes - * See {@link ValueProvider}, {@link ExistingProvider}, {@link FactoryProvider}. - * - * @description * 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` */ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvider | ConstructorProvider | FactoryProvider | any[]; /** - * @usageNotes - * ``` - * @Injectable() - * class MyService {} - * - * const provider: TypeProvider = MyService; - * ``` - * - * @description * Configures the `Injector` to return an instance of `Type` when `Type' is used as the token. * * Create an instance by invoking the `new` operator and supplying additional arguments. @@ -362,29 +283,19 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='TypeProvider'} - * - * */ export interface TypeProvider extends Type {} /** - * @usageNotes - * ``` - * - * class SomeClassImpl {} - * - * @Injectable(SomeModule, {useClass: SomeClassImpl}) - * class SomeClass {} - * ``` - * - * @description * Configures the `Injector` to return a value by invoking a `useClass` function. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ClassSansProvider'} @@ -399,27 +310,22 @@ export interface ClassSansProvider { } /** - * @usageNotes - * ``` - * @Injectable() - * class MyService {} - * - * const provider: ClassProvider = {provide: 'someToken', useClass: MyService}; - * ``` - * - * @description * Configures the `Injector` to return an instance of `useClass` for a token. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * + * @usageNotes * ### Example * * {@example core/di/ts/provider_spec.ts region='ClassProvider'} * * Note that following two providers are not equal: + * * {@example core/di/ts/provider_spec.ts region='ClassProviderDifference'} * + * ### Multi-value example * + * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ export interface ClassProvider extends ClassSansProvider { /** @@ -430,24 +336,18 @@ export interface ClassProvider extends ClassSansProvider { /** * If true, then 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. - * - * ### Example - * - * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'} */ multi?: boolean; } /** - * @usageNotes - * See {@link TypeProvider}, {@link ClassProvider}, {@link StaticProvider}. - * - * @description * Describes how the `Injector` should be configured. * * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection). * - * + * @see `TypeProvider` + * @see `ClassProvider` + * @see `StaticProvider` */ export type Provider = TypeProvider | ValueProvider | ClassProvider | ConstructorProvider | ExistingProvider | FactoryProvider | any[]; diff --git a/packages/core/src/di/reflective_errors.ts b/packages/core/src/di/reflective_errors.ts index 7351ebb99a..c88ffa441d 100644 --- a/packages/core/src/di/reflective_errors.ts +++ b/packages/core/src/di/reflective_errors.ts @@ -70,6 +70,7 @@ function addKey(this: InjectionError, injector: ReflectiveInjector, key: Reflect * Thrown when trying to retrieve a dependency by key from {@link Injector}, but the * {@link Injector} does not have a {@link Provider} for the given key. * + * @usageNotes * ### Example * * ```typescript @@ -90,6 +91,7 @@ export function noProviderError(injector: ReflectiveInjector, key: ReflectiveKey /** * Thrown when dependencies form a cycle. * + * @usageNotes * ### Example * * ```typescript @@ -116,6 +118,7 @@ export function cyclicDependencyError( * The `InstantiationError` class contains the original error plus the dependency graph which caused * this object to be instantiated. * + * @usageNotes * ### Example * * ```typescript @@ -149,6 +152,7 @@ export function instantiationError( * Thrown when an object other then {@link Provider} (or `Type`) is passed to {@link Injector} * creation. * + * @usageNotes * ### Example * * ```typescript @@ -166,6 +170,7 @@ export function invalidProviderError(provider: any) { * Lack of annotation information prevents the {@link Injector} from determining which dependencies * need to be injected into the constructor. * + * @usageNotes * ### Example * * ```typescript @@ -209,6 +214,7 @@ export function noAnnotationError(typeOrFunc: Type| Function, params: any[] /** * Thrown when getting an object by index. * + * @usageNotes * ### Example * * ```typescript @@ -228,6 +234,7 @@ export function outOfBoundsError(index: number) { /** * Thrown when a multi provider and a regular provider are bound to the same token. * + * @usageNotes * ### Example * * ```typescript diff --git a/packages/core/src/di/reflective_injector.ts b/packages/core/src/di/reflective_injector.ts index d7784cb38e..f11781f060 100644 --- a/packages/core/src/di/reflective_injector.ts +++ b/packages/core/src/di/reflective_injector.ts @@ -26,6 +26,7 @@ const UNDEFINED = new Object(); * In typical use, application code asks for the dependencies in the constructor and they are * resolved by the `Injector`. * + * @usageNotes * ### Example * * The following example creates an `Injector` configured to create `Engine` and `Car`. @@ -56,8 +57,9 @@ export abstract class ReflectiveInjector implements Injector { * Turns an array of provider definitions into an array of resolved providers. * * A resolution is a process of flattening multiple nested arrays and converting individual - * providers into an array of {@link ResolvedReflectiveProvider}s. + * providers into an array of `ResolvedReflectiveProvider`s. * + * @usageNotes * ### Example * * ```typescript @@ -83,7 +85,6 @@ export abstract class ReflectiveInjector implements Injector { * }); * ``` * - * See {@link ReflectiveInjector#fromResolvedProviders fromResolvedProviders} for more info. */ static resolve(providers: Provider[]): ResolvedReflectiveProvider[] { return resolveReflectiveProviders(providers); @@ -92,9 +93,10 @@ export abstract class ReflectiveInjector implements Injector { /** * Resolves an array of providers and creates an injector from those providers. * - * The passed-in providers can be an array of `Type`, {@link Provider}, + * The passed-in providers can be an array of `Type`, `Provider`, * or a recursive array of more providers. * + * @usageNotes * ### Example * * ```typescript @@ -110,11 +112,6 @@ export abstract class ReflectiveInjector implements Injector { * var injector = ReflectiveInjector.resolveAndCreate([Car, Engine]); * expect(injector.get(Car) instanceof Car).toBe(true); * ``` - * - * This function is slower than the corresponding `fromResolvedProviders` - * because it needs to resolve the passed-in providers first. - * See {@link ReflectiveInjector#resolve resolve} and - * {@link ReflectiveInjector#fromResolvedProviders fromResolvedProviders}. */ static resolveAndCreate(providers: Provider[], parent?: Injector): ReflectiveInjector { const ResolvedReflectiveProviders = ReflectiveInjector.resolve(providers); @@ -126,6 +123,7 @@ export abstract class ReflectiveInjector implements Injector { * * This API is the recommended way to construct injectors in performance-sensitive parts. * + * @usageNotes * ### Example * * ```typescript @@ -156,6 +154,7 @@ export abstract class ReflectiveInjector implements Injector { * * + * @usageNotes * ### Example * * ```typescript @@ -172,9 +171,10 @@ export abstract class ReflectiveInjector implements Injector { * * - * The passed-in providers can be an array of `Type`, {@link Provider}, + * The passed-in providers can be an array of `Type`, `Provider`, * or a recursive array of more providers. * + * @usageNotes * ### Example * * ```typescript @@ -188,11 +188,6 @@ export abstract class ReflectiveInjector implements Injector { * expect(child.get(ChildProvider) instanceof ChildProvider).toBe(true); * expect(child.get(ParentProvider)).toBe(parent.get(ParentProvider)); * ``` - * - * This function is slower than the corresponding `createChildFromResolved` - * because it needs to resolve the passed-in providers first. - * See {@link ReflectiveInjector#resolve resolve} and - * {@link ReflectiveInjector#createChildFromResolved createChildFromResolved}. */ abstract resolveAndCreateChild(providers: Provider[]): ReflectiveInjector; @@ -204,6 +199,7 @@ export abstract class ReflectiveInjector implements Injector { * * This API is the recommended way to construct injectors in performance-sensitive parts. * + * @usageNotes * ### Example * * ```typescript @@ -228,6 +224,7 @@ export abstract class ReflectiveInjector implements Injector { * * The created object does not get cached by the injector. * + * @usageNotes * ### Example * * ```typescript @@ -254,6 +251,7 @@ export abstract class ReflectiveInjector implements Injector { * * The created object does not get cached by the injector. * + * @usageNotes * ### Example * * ```typescript diff --git a/packages/core/src/di/reflective_provider.ts b/packages/core/src/di/reflective_provider.ts index f66bc9a02e..6d95966ddc 100644 --- a/packages/core/src/di/reflective_provider.ts +++ b/packages/core/src/di/reflective_provider.ts @@ -36,9 +36,10 @@ export class ReflectiveDependency { const _EMPTY_LIST: any[] = []; /** - * An internal resolved representation of a {@link Provider} used by the {@link Injector}. + * An internal resolved representation of a `Provider` used by the `Injector`. * - * It is usually created automatically by `Injector.resolveAndCreate`. + * @usageNotes + * This is usually created automatically by `Injector.resolveAndCreate`. * * It can be created manually, as follows: * @@ -81,8 +82,7 @@ export class ResolvedReflectiveProvider_ implements ResolvedReflectiveProvider { } /** - * An internal resolved representation of a factory function created by resolving {@link - * Provider}. + * An internal resolved representation of a factory function created by resolving `Provider`. * @experimental */ export class ResolvedReflectiveFactory { @@ -123,10 +123,10 @@ function resolveReflectiveFactory(provider: NormalizedProvider): ResolvedReflect } /** - * Converts the {@link Provider} into {@link ResolvedProvider}. + * Converts the `Provider` into `ResolvedProvider`. * - * {@link Injector} internally only uses {@link ResolvedProvider}, {@link Provider} contains - * convenience provider syntax. + * `Injector` internally only uses `ResolvedProvider`, `Provider` contains convenience provider + * syntax. */ function resolveReflectiveProvider(provider: NormalizedProvider): ResolvedReflectiveProvider { return new ResolvedReflectiveProvider_( @@ -145,9 +145,8 @@ export function resolveReflectiveProviders(providers: Provider[]): ResolvedRefle } /** - * Merges a list of ResolvedProviders into a list where - * each key is contained exactly once and multi providers - * have been merged. + * Merges a list of ResolvedProviders into a list where each key is contained exactly once and + * multi providers have been merged. */ export function mergeResolvedReflectiveProviders( providers: ResolvedReflectiveProvider[], diff --git a/packages/core/src/error_handler.ts b/packages/core/src/error_handler.ts index 62f17e84d3..da2b8af72c 100644 --- a/packages/core/src/error_handler.ts +++ b/packages/core/src/error_handler.ts @@ -11,14 +11,13 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError} /** - * - * @description * Provides a hook for centralized exception handling. * * The default implementation of `ErrorHandler` prints error messages to the `console`. To * intercept error handling, write a custom exception handler that replaces this default as * appropriate for your app. * + * @usageNotes * ### Example * * ``` @@ -33,8 +32,6 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError} * }) * class MyModule {} * ``` - * - * */ export class ErrorHandler { /** diff --git a/packages/core/src/event_emitter.ts b/packages/core/src/event_emitter.ts index bd46970b5c..582bb61fb6 100644 --- a/packages/core/src/event_emitter.ts +++ b/packages/core/src/event_emitter.ts @@ -11,6 +11,7 @@ import {Subject, Subscription} from 'rxjs'; /** * Use by directives and components to emit custom Events. * + * @usageNotes * ### Examples * * In the following example, `Zippy` alternatively emits `open` and `close` events when its @@ -49,6 +50,8 @@ import {Subject, Subscription} from 'rxjs'; * * ``` * + * ### Notes + * * Uses Rx.Observable but provides an adapter to make it work as specified here: * https://github.com/jhusain/observable-spec * diff --git a/packages/core/src/i18n/tokens.ts b/packages/core/src/i18n/tokens.ts index 55786e6db2..8565414028 100644 --- a/packages/core/src/i18n/tokens.ts +++ b/packages/core/src/i18n/tokens.ts @@ -15,6 +15,7 @@ import {InjectionToken} from '../di/injection_token'; * * See the [i18n guide](guide/i18n#setting-up-locale) for more information. * + * @usageNotes * ### Example * * ```typescript @@ -37,6 +38,7 @@ export const LOCALE_ID = new InjectionToken('LocaleId'); * * See the [i18n guide](guide/i18n#merge) for more information. * + * @usageNotes * ### Example * * ```typescript @@ -62,6 +64,7 @@ export const TRANSLATIONS = new InjectionToken('Translations'); * * See the [i18n guide](guide/i18n#merge) for more information. * + * @usageNotes * ### Example * * ```typescript @@ -87,6 +90,7 @@ export const TRANSLATIONS_FORMAT = new InjectionToken('TranslationsForma * * See the [i18n guide](guide/i18n#missing-translation) for more information. * + * @usageNotes * ### Example * ```typescript * import { MissingTranslationStrategy } from '@angular/core'; diff --git a/packages/core/src/linker/query_list.ts b/packages/core/src/linker/query_list.ts index dc72fd1588..eeb0026a16 100644 --- a/packages/core/src/linker/query_list.ts +++ b/packages/core/src/linker/query_list.ts @@ -27,6 +27,7 @@ import {getSymbolIterator} from '../util'; * * NOTE: In the future this class will implement an `Observable` interface. * + * @usageNotes * ### Example * ```typescript * @Component({...}) @@ -34,7 +35,6 @@ import {getSymbolIterator} from '../util'; * @ViewChildren(Item) items:QueryList; * } * ``` - * */ export class QueryList/* implements Iterable */ { public readonly dirty = true; diff --git a/packages/core/src/linker/view_ref.ts b/packages/core/src/linker/view_ref.ts index 47b721a5d8..ffeb9be846 100644 --- a/packages/core/src/linker/view_ref.ts +++ b/packages/core/src/linker/view_ref.ts @@ -29,9 +29,10 @@ export abstract class ViewRef extends ChangeDetectorRef { * * Properties of elements in a View can change, but the structure (number and order) of elements in * a View cannot. Changing the structure of Elements can only be done by inserting, moving or - * removing nested Views via a {@link ViewContainerRef}. Each View can contain many View Containers. + * removing nested Views via a `ViewContainerRef`. Each View can contain many View Containers. * * + * @usageNotes * ### Example * * Given this template... @@ -43,9 +44,10 @@ export abstract class ViewRef extends ChangeDetectorRef { * * ``` * - * We have two {@link TemplateRef}s: + * We have two `TemplateRef`s: + * + * Outer `TemplateRef`: * - * Outer {@link TemplateRef}: * ``` * Count: {{items.length}} *
    @@ -53,14 +55,15 @@ export abstract class ViewRef extends ChangeDetectorRef { *
* ``` * - * Inner {@link TemplateRef}: + * Inner `TemplateRef`: + * * ``` *
  • {{item}}
    • * ``` * - * Notice that the original template is broken down into two separate {@link TemplateRef}s. + * Notice that the original template is broken down into two separate `TemplateRef`s. * - * The outer/inner {@link TemplateRef}s are then assembled into views like so: + * The outer/inner `TemplateRef`s are then assembled into views like so: * * ``` * diff --git a/packages/core/src/metadata/di.ts b/packages/core/src/metadata/di.ts index fff3ae60e1..d25a9a52fa 100644 --- a/packages/core/src/metadata/di.ts +++ b/packages/core/src/metadata/di.ts @@ -16,6 +16,7 @@ import {makeParamDecorator, makePropDecorator} from '../util/decorators'; * All components that are referenced in the `useValue` value (either directly * or in a nested array or map) will be added to the `entryComponents` property. * + * @usageNotes * ### Example * The following example shows how the router can populate the `entryComponents` * field of an NgModule based on the router configuration which refers @@ -57,6 +58,7 @@ 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`. @@ -103,7 +105,6 @@ export interface Attribute { attributeName?: string; } /** * Attribute decorator and metadata. * - * * @Annotation */ export const Attribute: AttributeDecorator = @@ -111,8 +112,6 @@ export const Attribute: AttributeDecorator = /** * Type of the Query metadata. - * - * */ export interface Query { descendants: boolean; @@ -125,34 +124,25 @@ export interface Query { /** * Base class for query metadata. * - * See {@link ContentChildren}, {@link ContentChild}, {@link ViewChildren}, {@link ViewChild} for - * more information. - * - * + * @see `ContentChildren`. + * @see `ContentChild`. + * @see `ViewChildren`. + * @see `ViewChild`. */ export abstract class Query {} /** * Type of the ContentChildren decorator / constructor function. * - * See {@link ContentChildren}. - * - * + * @see `ContentChildren`. */ export interface ContentChildrenDecorator { /** - * - * @usageNotes - * - * {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'} - * - * @description * Configures a content query. * - * You can use ContentChildren to get the {@link QueryList} of elements or directives from the + * 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 - * updated, - * and the changes observable of the query list will emit a new value. + * updated, and the changes observable of the query list will emit a new value. * * Content queries are set before the `ngAfterContentInit` callback is called. * @@ -162,13 +152,20 @@ export interface ContentChildrenDecorator { * * **descendants** - include only direct children or all descendants. * * **read** - read a different token from the queried elements. * - * Let's look at an example: + * @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'} + * + * ### 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'} * - * **npm package**: `@angular/core` - * - * * @Annotation */ (selector: Type|Function|string, opts?: {descendants?: boolean, read?: any}): any; @@ -203,12 +200,6 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator( */ export interface ContentChildDecorator { /** - * - * @usageNotes - * - * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'} - * - * @description * Configures a content query. * * You can use ContentChild to get the first element or the directive matching the selector from @@ -222,13 +213,15 @@ export interface ContentChildDecorator { * * **selector** - the directive type or the name used for querying. * * **read** - read a different token from the queried element. * - * Let's look at an example: + * @usageNotes + * ### Example + * + * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'} + * + * ### Example * * {@example core/di/ts/contentChild/content_child_example.ts region='Component'} * - * **npm package**: `@angular/core` - * - * * @Annotation */ (selector: Type|Function|string, opts?: {read?: any}): any; @@ -238,7 +231,7 @@ export interface ContentChildDecorator { /** * Type of the ContentChild metadata. * - * See {@link ContentChild}. + * @see `ContentChild`. * * */ @@ -258,21 +251,15 @@ export const ContentChild: ContentChildDecorator = makePropDecorator( /** * Type of the ViewChildren decorator / constructor function. * - * See {@link ViewChildren}. + * @see `ViewChildren`. * * */ export interface ViewChildrenDecorator { /** - * - * @usageNotes - * - * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'} - * - * @description * Configures a view query. * - * You can use ViewChildren to get the {@link QueryList} of elements or directives from the + * 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, * and the changes observable of the query list will emit a new value. * @@ -283,13 +270,16 @@ export interface ViewChildrenDecorator { * * **selector** - the directive type or the name used for querying. * * **read** - read a different token from the queried elements. * - * Let's look at an example: + * @usageNotes + * + * ### Example + * + * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'} + * + * ### Example * * {@example core/di/ts/viewChildren/view_children_example.ts region='Component'} * - * **npm package**: `@angular/core` - * - * * @Annotation */ (selector: Type|Function|string, opts?: {read?: any}): any; @@ -298,15 +288,12 @@ export interface ViewChildrenDecorator { /** * Type of the ViewChildren metadata. - * - * */ export type ViewChildren = Query; /** * ViewChildren decorator and metadata. * - * * @Annotation */ export const ViewChildren: ViewChildrenDecorator = makePropDecorator( @@ -317,17 +304,10 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator( /** * Type of the ViewChild decorator / constructor function. * - * See {@link ViewChild} - * - * + * @see `ViewChild`. */ export interface ViewChildDecorator { /** - * - * @usageNotes - * - * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'} - * * @description * Configures a view query. * @@ -342,11 +322,16 @@ export interface ViewChildDecorator { * * **selector** - the directive type or the name used for querying. * * **read** - read a different token from the queried elements. * + * @usageNotes + * + * ### Example + * + * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'} + * + * ### Example + * * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} * - * **npm package**: `@angular/core` - * - * * @Annotation */ (selector: Type|Function|string, opts?: {read?: any}): any; @@ -355,15 +340,12 @@ export interface ViewChildDecorator { /** * Type of the ViewChild metadata. - * - * */ export type ViewChild = Query; /** * ViewChild decorator and metadata. * - * * @Annotation */ export const ViewChild: ViewChildDecorator = makePropDecorator( diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index afe89547fa..711c1855a4 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -16,25 +16,9 @@ import {ViewEncapsulation} from './view'; /** * Type of the Directive decorator / constructor function. - * - * */ export interface DirectiveDecorator { /** - * @usageNotes - * - * ``` - * import {Directive} from '@angular/core'; - * - * @Directive({ - * selector: 'my-directive', - * }) - * export class MyDirective { - * } - * ``` - * - * @description - * * Marks a class as an Angular directive and collects directive configuration * metadata. * @@ -65,13 +49,24 @@ export interface DirectiveDecorator { * * **queries** - configure queries that can be injected into the component * * **selector** - css selector that identifies this component in a template * + * @usageNotes + * + * ``` + * import {Directive} from '@angular/core'; + * + * @Directive({ + * selector: 'my-directive', + * }) + * export class MyDirective { + * } + * ``` * * @Annotation */ (obj: Directive): TypeDecorator; /** - * See the {@link Directive} decorator. + * See the `Directive` decorator. */ new (obj: Directive): Directive; } @@ -92,7 +87,7 @@ export interface Directive { * - `:not(sub_selector)`: select only if the element does not match the `sub_selector`. * - `selector1, selector2`: select if either `selector1` or `selector2` matches. * - * + * @usageNotes * ### Example * * Suppose we have a directive with an `input[type=text]` selector. @@ -124,6 +119,7 @@ export interface Directive { * * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`. * + * @usageNotes * ### Example * * The following example creates a component with two data-bound properties. @@ -153,7 +149,6 @@ export interface Directive { * }) * class App {} * ``` - * */ inputs?: string[]; @@ -169,6 +164,7 @@ export interface Directive { * - `directiveProperty` specifies the component property that emits events. * - `bindingProperty` specifies the DOM property the event handler is attached to. * + * @usageNotes * ### Example * * ```typescript @@ -198,14 +194,17 @@ export interface Directive { * everyFiveSeconds() { console.log('five seconds'); } * } * ``` - * */ outputs?: string[]; /** * Specify the events, actions, properties and attributes related to the host element. * - * ## Host Listeners + * @usageNotes + * The key corresponds to the name of the event, property or attribute on the host to + * bind. The value is formatted differently depending upon the type of the binding. + * + * ### Host Listeners * * Specifies which DOM events a directive listens to via a set of `(event)` to `method` * key-value pairs: @@ -220,8 +219,6 @@ export interface Directive { * * When writing a directive event binding, you can also refer to the $event local variable. * - * ### Example - * * The following example declares a directive that attaches a click listener to the button and * counts clicks. * @@ -247,15 +244,13 @@ export interface Directive { * class App {} * ``` * - * ## Host Property Bindings + * ### Host Property Bindings * * Specifies which DOM properties a directive updates. * * Angular automatically checks host property bindings during change detection. * If a binding changes, it will update the host element of the directive. * - * ### Example - * * The following example creates a directive that sets the `valid` and `invalid` classes * on the DOM element that has ngModel directive on it. * @@ -282,12 +277,10 @@ export interface Directive { * } * ``` * - * ## Attributes + * ### Attributes * * Specifies static attributes that should be propagated to a host element. * - * ### Example - * * In this example using `my-button` directive (ex.: `
    `) on a host element * (here: `
    ` ) will ensure that this element will get the "button" role. * @@ -308,7 +301,8 @@ export interface Directive { * Defines the set of injectable objects that are visible to a Directive and its light DOM * children. * - * ## Simple Example + * @usageNotes + * ### Simple Example * * Here is an example of a class that can be injected: * @@ -339,7 +333,8 @@ export interface Directive { /** * Defines the name that can be used in the template to assign this directive to a variable. * - * ## Simple Example + * @usageNotes + * ### Simple Example * * ``` * @Directive({ @@ -366,6 +361,7 @@ export interface Directive { * Content queries are set before the `ngAfterContentInit` callback is called. * View queries are set before the `ngAfterViewInit` callback is called. * + * @usageNotes * ### Example * * ``` @@ -397,7 +393,6 @@ export interface Directive { /** * Directive decorator and metadata. * - * * @Annotation */ export const Directive: DirectiveDecorator = makeDecorator( @@ -406,16 +401,9 @@ export const Directive: DirectiveDecorator = makeDecorator( /** * Type of the Component decorator / constructor function. - * - * */ export interface ComponentDecorator { /** - * @usageNotes - * - * {@example core/ts/metadata/metadata.ts region='component'} - * - * @description * Marks a class as an Angular component and collects component configuration * metadata. * @@ -459,24 +447,22 @@ export interface ComponentDecorator { * * **templateUrl** - url to an external file containing a template for the view * * **viewProviders** - list of providers available to this component and its view children * + * @usageNotes * ### Example * * {@example core/ts/metadata/metadata.ts region='component'} * - * * @Annotation */ (obj: Component): TypeDecorator; /** - * See the {@link Component} decorator. + * See the `Component` decorator. */ new (obj: Component): Component; } /** * Type of the Component metadata. - * - * */ export interface Component extends Directive { /** @@ -493,7 +479,8 @@ export interface Component extends Directive { /** * Defines the set of injectable objects that are visible to its view DOM children. * - * ## Simple Example + * @usageNotes + * ### Simple Example * * Here is an example of a class that can be injected: * @@ -535,8 +522,8 @@ export interface Component extends Directive { * In CommonJS, this can always be set to `module.id`, similarly SystemJS exposes `__moduleName` * variable within each module. * - * - * ## Simple Example + * @usageNotes + * ### Simple Example * * ``` * @Directive({ @@ -553,7 +540,7 @@ export interface Component extends Directive { /** * Specifies a template URL for an Angular component. * - *Only one of `templateUrl` or `template` can be defined per View. + * Only one of `templateUrl` or `template` can be defined per View. */ templateUrl?: string; @@ -586,9 +573,12 @@ export interface Component extends Directive { * * For animations to be available for use, animation state changes are placed within * {@link trigger animation triggers} which are housed inside of the `animations` annotation - * metadata. Within a trigger both {@link state state} and {@link transition transition} entries + * metadata. Within a trigger both `state` and `transition` entries * can be placed. * + * @usageNotes + * ### Example + * * ```typescript * @Component({ * selector: 'animation-cmp', @@ -636,28 +626,26 @@ export interface Component extends Directive { * Please visit each of the animation DSL functions listed below to gain a better understanding * of how and why they are used for crafting animations in Angular: * - * - {@link trigger trigger()} - * - {@link state state()} - * - {@link transition transition()} - * - {@link group group()} - * - {@link sequence sequence()} - * - {@link style style()} - * - {@link animate animate()} - * - {@link keyframes keyframes()} + * - `trigger()` + * - `state()` + * - `transition()` + * - `group()` + * - `sequence()` + * - `style()` + * - `animate()` + * - `keyframes()` */ animations?: any[]; /** * Specifies how the template and the styles should be encapsulated: - * - {@link ViewEncapsulation#Native `ViewEncapsulation.Native`} to use shadow roots - only works - * if natively available on the platform, - * - {@link ViewEncapsulation#Emulated `ViewEncapsulation.Emulated`} to use shimmed CSS that - * emulates the native behavior, - * - {@link ViewEncapsulation#None `ViewEncapsulation.None`} to use global CSS without any - * encapsulation. + * - `ViewEncapsulation.Native` to use shadow roots - only works if natively available on the + * platform, + * - `ViewEncapsulation.Emulated` to use shimmed CSS that emulates the native behavior, + * - `ViewEncapsulation.None` to use global CSS without any encapsulation. * * When no `encapsulation` is defined for the component, the default value from the - * {@link CompilerOptions} is used. The default is `ViewEncapsulation.Emulated`}. Provide a new + * `CompilerOptions` is used. The default is `ViewEncapsulation.Emulated`. Provide a new * `CompilerOptions` to override this value. * * If the encapsulation is set to `ViewEncapsulation.Emulated` and the component has no `styles` @@ -673,13 +661,13 @@ export interface Component extends Directive { /** * Defines the components that should be compiled as well when * this component is defined. For each components listed here, - * Angular will create a {@link ComponentFactory} and store it in the - * {@link ComponentFactoryResolver}. + * Angular will create a `ComponentFactory` and store it in the + * `ComponentFactoryResolver`. */ entryComponents?: Array|any[]>; /** - * If {@link Component#preserveWhitespaces Component.preserveWhitespaces} is set to `false` + * If `Component.preserveWhitespaces` is set to `false` * potentially superfluous whitespace characters (ones matching the `\s` character class in * JavaScript regular expressions) will be removed from a compiled template. This can greatly * reduce AOT-generated code size as well as speed up view creation. @@ -750,7 +738,6 @@ export interface Component extends Directive { /** * Component decorator and metadata. * - * * @Annotation */ export const Component: ComponentDecorator = makeDecorator( @@ -760,8 +747,6 @@ export const Component: ComponentDecorator = makeDecorator( /** * Type of the Pipe decorator / constructor function. - * - * */ export interface PipeDecorator { /** @@ -774,15 +759,13 @@ export interface PipeDecorator { (obj: Pipe): TypeDecorator; /** - * See the {@link Pipe} decorator. + * See the `Pipe` decorator. */ new (obj: Pipe): Pipe; } /** * Type of the Pipe metadata. - * - * */ export interface Pipe { /** @@ -810,11 +793,10 @@ export interface Pipe { * Pipe decorator and metadata. * * Use the `@Pipe` annotation to declare that a given class is a pipe. A pipe - * class must also implement {@link PipeTransform} interface. + * class must also implement `PipeTransform` interface. * * To use the pipe include a reference to the pipe class in - * {@link NgModule#declarations}. - * + * `NgModule.declarations`. * * @Annotation */ @@ -865,7 +847,6 @@ export interface InputDecorator { * * class App {} * ``` - * */ (bindingPropertyName?: string): any; new (bindingPropertyName?: string): any; @@ -873,8 +854,6 @@ export interface InputDecorator { /** * Type of the Input metadata. - * - * */ export interface Input { /** @@ -886,7 +865,6 @@ export interface Input { /** * Input decorator and metadata. * - * * @Annotation */ export const Input: InputDecorator = @@ -894,8 +872,6 @@ export const Input: InputDecorator = /** * Type of the Output decorator / constructor function. - * - * */ export interface OutputDecorator { /** @@ -908,6 +884,7 @@ export interface OutputDecorator { * used when instantiating a component in the template. When not provided, * the name of the decorated property is used. * + * @usageNotes * ### Example * * ```typescript @@ -944,15 +921,12 @@ export interface OutputDecorator { /** * Type of the Output metadata. - * - * */ export interface Output { bindingPropertyName?: string; } /** * Output decorator and metadata. * - * * @Annotation */ export const Output: OutputDecorator = @@ -961,8 +935,6 @@ export const Output: OutputDecorator = /** * Type of the HostBinding decorator / constructor function. - * - * */ export interface HostBindingDecorator { /** @@ -975,6 +947,7 @@ export interface HostBindingDecorator { * name of the host element that will be updated. When not provided, * the class property name is used. * + * @usageNotes * ### Example * * The following example creates a directive that sets the `valid` and `invalid` classes @@ -996,7 +969,6 @@ export interface HostBindingDecorator { * prop; * } * ``` - * */ (hostPropertyName?: string): any; new (hostPropertyName?: string): any; @@ -1004,15 +976,12 @@ export interface HostBindingDecorator { /** * Type of the HostBinding metadata. - * - * */ export interface HostBinding { hostPropertyName?: string; } /** * HostBinding decorator and metadata. * - * * @Annotation */ export const HostBinding: HostBindingDecorator = @@ -1021,8 +990,6 @@ export const HostBinding: HostBindingDecorator = /** * Type of the HostListener decorator / constructor function. - * - * */ export interface HostListenerDecorator { /** @@ -1032,6 +999,7 @@ export interface HostListenerDecorator { * * If the decorated method returns `false`, then `preventDefault` is applied on the DOM event. * + * @usageNotes * ### Example * * The following example declares a directive that attaches a click listener to the button and @@ -1063,8 +1031,6 @@ export interface HostListenerDecorator { /** * Type of the HostListener metadata. - * - * */ export interface HostListener { eventName?: string; @@ -1074,7 +1040,6 @@ export interface HostListener { /** * HostListener decorator and metadata. * - * * @Annotation */ export const HostListener: HostListenerDecorator = diff --git a/packages/core/src/render3/view_ref.ts b/packages/core/src/render3/view_ref.ts index bf6a6d2fb9..e88cdd489b 100644 --- a/packages/core/src/render3/view_ref.ts +++ b/packages/core/src/render3/view_ref.ts @@ -57,6 +57,7 @@ export class ViewRef implements viewEngine_EmbeddedViewRef, viewEngine_Int * * * + * @usageNotes * ### Example * * ```typescript @@ -91,6 +92,7 @@ export class ViewRef implements viewEngine_EmbeddedViewRef, viewEngine_Int * * * + * @usageNotes * ### Example * * The following example defines a component with a large list of readonly data. @@ -142,6 +144,7 @@ export class ViewRef implements viewEngine_EmbeddedViewRef, viewEngine_Int * * * + * @usageNotes * ### Example * * The following example creates a component displaying `live` data. The component will detach @@ -200,6 +203,7 @@ export class ViewRef implements viewEngine_EmbeddedViewRef, viewEngine_Int * * * + * @usageNotes * ### Example * * The following example defines a component with a large list of readonly data. diff --git a/packages/core/src/zone/ng_zone.ts b/packages/core/src/zone/ng_zone.ts index bd410c78a0..17b68225d8 100644 --- a/packages/core/src/zone/ng_zone.ts +++ b/packages/core/src/zone/ng_zone.ts @@ -24,6 +24,7 @@ import {EventEmitter} from '../event_emitter'; * - link to runOutsideAngular/run (throughout this file!) * --> * + * @usageNotes * ### Example * * ``` diff --git a/packages/core/testing/src/fake_async.ts b/packages/core/testing/src/fake_async.ts index 6758643a2b..e7b9e221f0 100644 --- a/packages/core/testing/src/fake_async.ts +++ b/packages/core/testing/src/fake_async.ts @@ -33,7 +33,8 @@ export function resetFakeAsyncZone(): void { * * Can be used to wrap inject() calls. * - * ## Example + * @usageNotes + * ### Example * * {@example core/testing/ts/fake_async.ts region='basic'} * @@ -56,7 +57,8 @@ export function fakeAsync(fn: Function): (...args: any[]) => any { * The microtasks queue is drained at the very start of this function and after any timer callback * has been executed. * - * ## Example + * @usageNotes + * ### Example * * {@example core/testing/ts/fake_async.ts region='basic'} * diff --git a/packages/core/testing/src/fake_async_fallback.ts b/packages/core/testing/src/fake_async_fallback.ts index 4819f5c129..7971726465 100644 --- a/packages/core/testing/src/fake_async_fallback.ts +++ b/packages/core/testing/src/fake_async_fallback.ts @@ -43,7 +43,8 @@ let _inFakeAsyncCall = false; * * Can be used to wrap inject() calls. * - * ## Example + * @usageNotes + * ### Example * * {@example core/testing/ts/fake_async.ts region='basic'} * @@ -110,7 +111,8 @@ function _getFakeAsyncZoneSpec(): any { * The microtasks queue is drained at the very start of this function and after any timer callback * has been executed. * - * ## Example + * @usageNotes + * ### Example * * {@example core/testing/ts/fake_async.ts region='basic'} *