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