iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix invalid headings (#24000) 

PR Close #24000
This commit is contained in:
Pete Bacon Darwin 2018-05-18 16:13:00 +01:00 committed by Miško Hevery
parent 77309e2ea4
commit e6516b0229
26 changed files with 255 additions and 473 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
packages/animations/src/animation_metadata.ts
View File

@ -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()`

15
packages/core/src/application_ref.ts
View File

@ -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<T extends Object>(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'}

6
packages/core/src/change_detection/change_detector_ref.ts
View File

@ -16,6 +16,7 @@ export abstract class ChangeDetectorRef {
*
* <!-- TODO: Add a link to a chapter on OnPush components -->
*
* @usageNotes
* ### Example
*
* ```typescript
@ -50,6 +51,7 @@ export abstract class ChangeDetectorRef {
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* @usageNotes
* ### Example
*
* The following example defines a component with a large list of readonly data.
@ -102,9 +104,8 @@ export abstract class ChangeDetectorRef {
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* ### 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 {
*
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
*
* @usageNotes
* ### Example
*
* The following example creates a component displaying `live` data. The component will detach

5
packages/core/src/change_detection/differs/iterable_differs.ts
View File

@ -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: [

5
packages/core/src/change_detection/differs/keyvalue_differs.ts
View File

@ -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: [

5
packages/core/src/change_detection/pipe_transform.ts
View File

@ -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:

10
packages/core/src/di/forward_ref.ts
View File

@ -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<any> {
*
* 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 {

20
packages/core/src/di/injectable.ts
View File

@ -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<any>| 'root' | null}&InjectableProvider): any;
@ -125,7 +116,6 @@ function preR3InjectableCompile(
/**
* Injectable decorator and metadata.
*
*
* @Annotation
*/
export const Injectable: InjectableDecorator = makeDecorator(

12
packages/core/src/di/injection_token.ts
View File

@ -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<T> {

16
packages/core/src/di/injector.ts
View File

@ -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'}
*

89
packages/core/src/di/metadata.ts
View File

@ -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');

180
packages/core/src/di/provider.ts
View File

@ -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<any> {}
/**
* @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[];

7
packages/core/src/di/reflective_errors.ts
View File

@ -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<any>| 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

26
packages/core/src/di/reflective_injector.ts
View File

@ -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 {
* <!-- TODO: Add a link to the section of the user guide talking about hierarchical injection.
* -->
*
* @usageNotes
* ### Example
*
* ```typescript
@ -172,9 +171,10 @@ export abstract class ReflectiveInjector implements Injector {
* <!-- TODO: Add a link to the section of the user guide talking about hierarchical injection.
* -->
*
* 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

19
packages/core/src/di/reflective_provider.ts
View File

@ -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[],

5
packages/core/src/error_handler.ts
View File

@ -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 {
/**

3
packages/core/src/event_emitter.ts
View File

@ -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';
* <zippy (open)="onOpen($event)" (close)="onClose($event)"></zippy>
* ```
*
* ### Notes
*
* Uses Rx.Observable but provides an adapter to make it work as specified here:
* https://github.com/jhusain/observable-spec
*

4
packages/core/src/i18n/tokens.ts
View File

@ -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<string>('LocaleId');
*
* See the [i18n guide](guide/i18n#merge) for more information.
*
* @usageNotes
* ### Example
*
* ```typescript
@ -62,6 +64,7 @@ export const TRANSLATIONS = new InjectionToken<string>('Translations');
*
* See the [i18n guide](guide/i18n#merge) for more information.
*
* @usageNotes
* ### Example
*
* ```typescript
@ -87,6 +90,7 @@ export const TRANSLATIONS_FORMAT = new InjectionToken<string>('TranslationsForma
*
* See the [i18n guide](guide/i18n#missing-translation) for more information.
*
* @usageNotes
* ### Example
* ```typescript
* import { MissingTranslationStrategy } from '@angular/core';

2
packages/core/src/linker/query_list.ts
View File

@ -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<Item>;
* }
* ```
*
*/
export class QueryList<T>/* implements Iterable<T> */ {
public readonly dirty = true;

15
packages/core/src/linker/view_ref.ts
View File

@ -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.
* <!-- /TODO -->
*
* @usageNotes
* ### Example
*
* Given this template...
@ -43,9 +44,10 @@ export abstract class ViewRef extends ChangeDetectorRef {
* </ul>
* ```
*
* We have two {@link TemplateRef}s:
* We have two `TemplateRef`s:
*
* Outer `TemplateRef`:
*
* Outer {@link TemplateRef}:
* ```
* Count: {{items.length}}
* <ul>
@ -53,14 +55,15 @@ export abstract class ViewRef extends ChangeDetectorRef {
* </ul>
* ```
*
* Inner {@link TemplateRef}:
* Inner `TemplateRef`:
*
* ```
* <li>{{item}}</li>
* ```
*
* 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:
*
* ```
* <!-- ViewRef: outer-0 -->

108
packages/core/src/metadata/di.ts
View File

@ -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 `<input>` 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<any>|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<any>|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<any>|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<any>|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(

155
packages/core/src/metadata/directives.ts
View File

@ -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.: `<div my-button></div>`) on a host element
* (here: `<div>` ) 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<Type<any>|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 =

4
packages/core/src/render3/view_ref.ts
View File

@ -57,6 +57,7 @@ export class ViewRef<T> implements viewEngine_EmbeddedViewRef<T>, viewEngine_Int
*
* <!-- TODO: Add a link to a chapter on OnPush components -->
*
* @usageNotes
* ### Example
*
* ```typescript
@ -91,6 +92,7 @@ export class ViewRef<T> implements viewEngine_EmbeddedViewRef<T>, viewEngine_Int
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* @usageNotes
* ### Example
*
* The following example defines a component with a large list of readonly data.
@ -142,6 +144,7 @@ export class ViewRef<T> implements viewEngine_EmbeddedViewRef<T>, viewEngine_Int
*
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
*
* @usageNotes
* ### Example
*
* The following example creates a component displaying `live` data. The component will detach
@ -200,6 +203,7 @@ export class ViewRef<T> implements viewEngine_EmbeddedViewRef<T>, viewEngine_Int
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* @usageNotes
* ### Example
*
* The following example defines a component with a large list of readonly data.

1
packages/core/src/zone/ng_zone.ts
View File

@ -24,6 +24,7 @@ import {EventEmitter} from '../event_emitter';
* - link to runOutsideAngular/run (throughout this file!)
* -->
*
* @usageNotes
* ### Example
*
* ```

6
packages/core/testing/src/fake_async.ts
View File

@ -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'}
*

6
packages/core/testing/src/fake_async_fallback.ts
View File

@ -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'}
*