docs: fix invalid headings (#24000)

PR Close #24000

packages/animations/src/animation_metadata.ts

@@ -42,8 +42,8 @@ export declare type AnimateTimings = {
  * @description Options that control animation styling and timing.
  * The following animation functions accept `AnimationOptions` data:
  *
- * - `transition`
+ * - `transition()`
- * - `sequence`
+ * - `sequence()`
  * - `group()`
  * - `query()`
  * - `animation()`

packages/core/src/application_ref.ts

@@ -180,8 +180,6 @@ export interface BootstrapOptions {
  *
  * A page's platform is initialized implicitly when a platform is created via a platform factory
  * (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function.
- *
- *
  */
 @Injectable()
 export class PlatformRef {
@@ -196,7 +194,8 @@ export class PlatformRef {
    * Creates an instance of an `@NgModule` for the given platform
    * for offline compilation.
    *
-   * ## Simple Example
+   * @usageNotes
+   * ### Simple Example
    *
    * ```typescript
    * my_module.ts:
@@ -252,7 +251,8 @@ export class PlatformRef {
   /**
    * Creates an instance of an `@NgModule` for a given platform using the given runtime compiler.
    *
-   * ## Simple Example
+   * @usageNotes
+   * ### Simple Example
    *
    * ```typescript
    * @NgModule({
@@ -358,8 +358,6 @@ function optionsReducer<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'}

packages/core/src/change_detection/change_detector_ref.ts

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

packages/core/src/change_detection/differs/iterable_differs.ts

@@ -162,12 +162,13 @@ export class IterableDiffers {
    * inherited {@link IterableDiffers} instance with the provided factories and return a new
    * {@link IterableDiffers} instance.
    *
+   * @usageNotes
+   * ### Example
+   *
    * The following example shows how to extend an existing list of factories,
    * which will only be applied to the injector for this component and its children.
    * This step is all that's required to make a new {@link IterableDiffer} available.
    *
-   * ### Example
-   *
    * ```
    * @Component({
    *   viewProviders: [

packages/core/src/change_detection/differs/keyvalue_differs.ts

@@ -135,12 +135,13 @@ export class KeyValueDiffers {
    * inherited {@link KeyValueDiffers} instance with the provided factories and return a new
    * {@link KeyValueDiffers} instance.
    *
+   * @usageNotes
+   * ### Example
+   *
    * The following example shows how to extend an existing list of factories,
    * which will only be applied to the injector for this component and its children.
    * This step is all that's required to make a new {@link KeyValueDiffer} available.
    *
-   * ### Example
-   *
    * ```
    * @Component({
    *   viewProviders: [

packages/core/src/change_detection/pipe_transform.ts

@@ -12,10 +12,7 @@
  * Angular invokes the `transform` method with the value of a binding
  * as the first argument, and any parameters as the second argument in list form.
  *
- * ## Syntax
+ * @usageNotes
- *
- * `value | pipeName[:arg0[:arg1...]]`
- *
  * ### Example
  *
  * The `RepeatPipe` below repeats the value as many times as indicated by the first argument:

packages/core/src/di/forward_ref.ts

@@ -14,6 +14,7 @@ import {stringify} from '../util';
 /**
  * An interface that a function passed into {@link forwardRef} has to implement.
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref_fn'}
@@ -25,10 +26,10 @@ export interface ForwardRefFn { (): any; }
  * Allows to refer to references which are not yet defined.
  *
  * For instance, `forwardRef` is used when the `token` which we need to refer to for the purposes of
- * DI is declared,
+ * DI is declared, but not yet defined. It is also used when the `token` which we use when creating
- * but not yet defined. It is also used when the `token` which we use when creating a query is not
+ * a query is not yet defined.
- * 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 {

packages/core/src/di/injectable.ts

@@ -30,32 +30,23 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
 
 /**
  * Type of the Injectable decorator / constructor function.
- *
- *
  */
 export interface InjectableDecorator {
   /**
+   * A marker metadata that marks a class as available to `Injector` for creation.
+   *
+   * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+   *
    * @usageNotes
-   * ```
-   * @Injectable()
-   * class Car {}
-   * ```
-   *
-   * @description
-   * A marker metadata that marks a class as available to {@link Injector} for creation.
-   *
-   * For more details, see the ["Dependency Injection Guide"(guide/dependency-injection).
-   *
    * ### Example
    *
    * {@example core/di/ts/metadata_spec.ts region='Injectable'}
    *
-   * {@link Injector} will throw an error when trying to instantiate a class that
+   * `Injector` will throw an error when trying to instantiate a class that
    * does not have `@Injectable` marker, as shown in the example below.
    *
    * {@example core/di/ts/metadata_spec.ts region='InjectableThrows'}
    *
-   *
    */
   (): any;
   (options?: {providedIn: Type<any>| 'root' | null}&InjectableProvider): any;
@@ -125,7 +116,6 @@ function preR3InjectableCompile(
 /**
 * Injectable decorator and metadata.
 *
-*
 * @Annotation
 */
 export const Injectable: InjectableDecorator = makeDecorator(

packages/core/src/di/injection_token.ts

@@ -36,16 +36,14 @@ import {InjectableDef, defineInjectable} from './defs';
  * overrides the above behavior and marks the token as belonging to a particular `@NgModule`. As
  * mentioned above, `'root'` is the default value for `providedIn`.
  *
- * ### Example
+ * @usageNotes
- *
+ * ### Basic Example
- * #### Tree-shakeable InjectionToken
- *
- * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'}
- *
- * #### Plain InjectionToken
  *
  * {@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> {

packages/core/src/di/injector.ts

@@ -43,23 +43,17 @@ export class NullInjector implements Injector {
 }
 
 /**
- * @usageNotes
- * ```
- * const injector: Injector = ...;
- * injector.get(...);
- * ```
- *
- * @description
- *
  * Concrete injectors implement this interface.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/injector_spec.ts region='Injector'}
  *
  * `Injector` returns itself when given `Injector` as a token:
+ *
  * {@example core/di/ts/injector_spec.ts region='injectInjector'}
  *
  *
@@ -92,6 +86,7 @@ export abstract class Injector {
   /**
    * Create a new Injector which is configure using `StaticProvider`s.
    *
+   * @usageNotes
    * ### Example
    *
    * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
@@ -450,7 +445,10 @@ export function setCurrentInjector(injector: Injector | null | undefined): Injec
  * Injects a token from the currently active injector.
  *
  * This function must be used in the context of a factory function such as one defined for an
- * `InjectionToken`, and will throw an error if not called from such a context. For example:
+ * `InjectionToken`, and will throw an error if not called from such a context.
+ *
+ * @usageNotes
+ * ### Example
  *
  * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'}
  *

packages/core/src/di/metadata.ts

@@ -15,36 +15,24 @@ import {EMPTY_ARRAY} from '../view/util';
 
 /**
  * Type of the Inject decorator / constructor function.
- *
- *
  */
 export interface InjectDecorator {
   /**
-   * @usageNotes
-   * ```
-   * @Injectable()
-   * class Car {
-   *   constructor(@Inject("MyEngine") public engine:Engine) {}
-   * }
-   * ```
-   *
-   * @description
    * A parameter decorator that specifies a dependency.
    *
    * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
    *
+   * @usageNotes
    * ### Example
    *
    * {@example core/di/ts/metadata_spec.ts region='Inject'}
    *
-   * When `@Inject()` is not present, {@link Injector} will use the type annotation of the
+   * When `@Inject()` is not present, `Injector` will use the type annotation of the
    * parameter.
    *
    * ### Example
    *
    * {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'}
-   *
-   *
    */
   (token: any): any;
   new (token: any): Inject;
@@ -52,15 +40,12 @@ export interface InjectDecorator {
 
 /**
  * Type of the Inject metadata.
- *
- *
  */
 export interface Inject { token: any; }
 
 /**
  * Inject decorator and metadata.
  *
- *
  * @Annotation
  */
 export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any) => ({token}));
@@ -68,30 +53,18 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
 
 /**
  * Type of the Optional decorator / constructor function.
- *
- *
  */
 export interface OptionalDecorator {
   /**
-   * @usageNotes
-   * ```
-   * @Injectable()
-   * class Car {
-   *   constructor(@Optional() public engine:Engine) {}
-   * }
-   * ```
-   *
-   * @description
    * A parameter metadata that marks a dependency as optional.
-   * {@link Injector} provides `null` if the dependency is not found.
+   * `Injector` provides `null` if the dependency is not found.
    *
    * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
    *
+   * @usageNotes
    * ### Example
    *
    * {@example core/di/ts/metadata_spec.ts region='Optional'}
-   *
-   *
    */
   (): any;
   new (): Optional;
@@ -99,44 +72,29 @@ export interface OptionalDecorator {
 
 /**
  * Type of the Optional metadata.
- *
- *
  */
 export interface Optional {}
 
 /**
  * Optional decorator and metadata.
  *
- *
  * @Annotation
  */
 export const Optional: OptionalDecorator = makeParamDecorator('Optional');
 
 /**
  * Type of the Self decorator / constructor function.
- *
- *
  */
 export interface SelfDecorator {
   /**
-   * @usageNotes
+   * Specifies that an `Injector` should retrieve a dependency only from itself.
-   * ```
-   * @Injectable()
-   * class Car {
-   *   constructor(@Self() public engine:Engine) {}
-   * }
-   * ```
-   *
-   * @description
-   * Specifies that an {@link 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');

packages/core/src/di/provider.ts

@@ -9,17 +9,11 @@
 import {Type} from '../type';
 
 /**
- * @usageNotes
- * ```
- * @Injectable(SomeModule, {useValue: 'someValue'})
- * class SomeClass {}
- * ```
- *
- * @description
  * Configures the `Injector` to return a value for a token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='ValueSansProvider'}
@@ -34,21 +28,18 @@ export interface ValueSansProvider {
 }
 
 /**
- * @usageNotes
- * ```
- * const provider: ValueProvider = {provide: 'someToken', useValue: 'someValue'};
- * ```
- *
- * @description
  * Configures the `Injector` to return a value for a token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='ValueProvider'}
  *
+ * ### Multi-value example
  *
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
  */
 export interface ValueProvider extends ValueSansProvider {
   /**
@@ -59,26 +50,16 @@ export interface ValueProvider extends ValueSansProvider {
   /**
    * If true, then injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
-   *
-   * ### Example
-   *
-   * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
    */
   multi?: boolean;
 }
 
 /**
- * @usageNotes
- * ```
- * @Injectable(SomeModule, {useClass: MyService, deps: []})
- * class MyService {}
- * ```
- *
- * @description
  * Configures the `Injector` to return an instance of `useClass` for a token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='StaticClassSansProvider'}
@@ -100,27 +81,22 @@ export interface StaticClassSansProvider {
 }
 
 /**
- * @usageNotes
- * ```
- * @Injectable()
- * class MyService {}
- *
- * const provider: ClassProvider = {provide: 'someToken', useClass: MyService, deps: []};
- * ```
- *
- * @description
  * Configures the `Injector` to return an instance of `useClass` for a token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='StaticClassProvider'}
  *
  * Note that following two providers are not equal:
+ *
  * {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference'}
  *
+ * ### Multi-value example
  *
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
  */
 export interface StaticClassProvider extends StaticClassSansProvider {
   /**
@@ -131,26 +107,23 @@ export interface StaticClassProvider extends StaticClassSansProvider {
   /**
    * If true, then injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
-   *
-   * ### Example
-   *
-   * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
    */
   multi?: boolean;
 }
 
 /**
+ * Configures the `Injector` to return an instance of a token.
+ *
+ * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ *
  * @usageNotes
+ * ### Example
+ *
  * ```
  * @Injectable(SomeModule, {deps: []})
  * class MyService {}
  * ```
  *
- * @description
- * Configures the `Injector` to return an instance of a token.
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
- *
  * @experimental
  */
 export interface ConstructorSansProvider {
@@ -162,24 +135,18 @@ export interface ConstructorSansProvider {
 }
 
 /**
- * @usageNotes
- * ```
- * @Injectable()
- * class MyService {}
- *
- * const provider: ClassProvider = {provide: MyClass, deps: []};
- * ```
- *
- * @description
  * Configures the `Injector` to return an instance of a token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
  *
+ * ### Multi-value example
  *
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
  */
 export interface ConstructorProvider extends ConstructorSansProvider {
   /**
@@ -190,31 +157,19 @@ export interface ConstructorProvider extends ConstructorSansProvider {
   /**
    * If true, then injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
-   *
-   * ### Example
-   *
-   * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
    */
   multi?: boolean;
 }
 
 /**
- * @usageNotes
- * ```
- * @Injectable(SomeModule, {useExisting: 'someOtherToken'})
- * class SomeClass {}
- * ```
- *
- * @description
  * Configures the `Injector` to return a value of another `useExisting` token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='ExistingSansProvider'}
- *
- *
  */
 export interface ExistingSansProvider {
   /**
@@ -224,21 +179,18 @@ export interface ExistingSansProvider {
 }
 
 /**
- * @usageNotes
- * ```
- * const provider: ExistingProvider = {provide: 'someToken', useExisting: 'someOtherToken'};
- * ```
- *
- * @description
  * Configures the `Injector` to return a value of another `useExisting` token.
  *
  * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
  *
+ * @usageNotes
  * ### Example
  *
  * {@example core/di/ts/provider_spec.ts region='ExistingProvider'}
  *
+ * ### Multi-value example
  *
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
  */
 export interface ExistingProvider extends ExistingSansProvider {
   /**
@@ -249,28 +201,16 @@ 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'}
@@ -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[];

packages/core/src/di/reflective_errors.ts

@@ -70,6 +70,7 @@ function addKey(this: InjectionError, injector: ReflectiveInjector, key: Reflect
  * Thrown when trying to retrieve a dependency by key from {@link Injector}, but the
  * {@link Injector} does not have a {@link Provider} for the given key.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -90,6 +91,7 @@ export function noProviderError(injector: ReflectiveInjector, key: ReflectiveKey
 /**
  * Thrown when dependencies form a cycle.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -116,6 +118,7 @@ export function cyclicDependencyError(
  * The `InstantiationError` class contains the original error plus the dependency graph which caused
  * this object to be instantiated.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -149,6 +152,7 @@ export function instantiationError(
  * Thrown when an object other then {@link Provider} (or `Type`) is passed to {@link Injector}
  * creation.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -166,6 +170,7 @@ export function invalidProviderError(provider: any) {
  * Lack of annotation information prevents the {@link Injector} from determining which dependencies
  * need to be injected into the constructor.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -209,6 +214,7 @@ export function noAnnotationError(typeOrFunc: Type<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

packages/core/src/di/reflective_injector.ts

@@ -26,6 +26,7 @@ const UNDEFINED = new Object();
  * In typical use, application code asks for the dependencies in the constructor and they are
  * resolved by the `Injector`.
  *
+ * @usageNotes
  * ### Example
  *
  * The following example creates an `Injector` configured to create `Engine` and `Car`.
@@ -56,8 +57,9 @@ export abstract class ReflectiveInjector implements Injector {
    * Turns an array of provider definitions into an array of resolved providers.
    *
    * A resolution is a process of flattening multiple nested arrays and converting individual
-   * providers into an array of {@link ResolvedReflectiveProvider}s.
+   * providers into an array of `ResolvedReflectiveProvider`s.
    *
+   * @usageNotes
    * ### Example
    *
    * ```typescript
@@ -83,7 +85,6 @@ export abstract class ReflectiveInjector implements Injector {
    * });
    * ```
    *
-   * See {@link ReflectiveInjector#fromResolvedProviders fromResolvedProviders} for more info.
    */
   static resolve(providers: Provider[]): ResolvedReflectiveProvider[] {
     return resolveReflectiveProviders(providers);
@@ -92,9 +93,10 @@ export abstract class ReflectiveInjector implements Injector {
   /**
    * Resolves an array of providers and creates an injector from those providers.
    *
-   * The passed-in providers can be an array of `Type`, {@link Provider},
+   * The passed-in providers can be an array of `Type`, `Provider`,
    * or a recursive array of more providers.
    *
+   * @usageNotes
    * ### Example
    *
    * ```typescript
@@ -110,11 +112,6 @@ export abstract class ReflectiveInjector implements Injector {
    * var injector = ReflectiveInjector.resolveAndCreate([Car, Engine]);
    * expect(injector.get(Car) instanceof Car).toBe(true);
    * ```
-   *
-   * This function is slower than the corresponding `fromResolvedProviders`
-   * because it needs to resolve the passed-in providers first.
-   * See {@link ReflectiveInjector#resolve resolve} and
-   * {@link ReflectiveInjector#fromResolvedProviders fromResolvedProviders}.
    */
   static resolveAndCreate(providers: Provider[], parent?: Injector): ReflectiveInjector {
     const ResolvedReflectiveProviders = ReflectiveInjector.resolve(providers);
@@ -126,6 +123,7 @@ export abstract class ReflectiveInjector implements Injector {
    *
    * This API is the recommended way to construct injectors in performance-sensitive parts.
    *
+   * @usageNotes
    * ### Example
    *
    * ```typescript
@@ -156,6 +154,7 @@ export abstract class ReflectiveInjector implements Injector {
    * <!-- 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

packages/core/src/di/reflective_provider.ts

@@ -36,9 +36,10 @@ export class ReflectiveDependency {
 const _EMPTY_LIST: any[] = [];
 
 /**
- * An internal resolved representation of a {@link Provider} used by the {@link Injector}.
+ * An internal resolved representation of a `Provider` used by the `Injector`.
  *
- * It is usually created automatically by `Injector.resolveAndCreate`.
+ * @usageNotes
+ * This is usually created automatically by `Injector.resolveAndCreate`.
  *
  * It can be created manually, as follows:
  *
@@ -81,8 +82,7 @@ export class ResolvedReflectiveProvider_ implements ResolvedReflectiveProvider {
 }
 
 /**
- * An internal resolved representation of a factory function created by resolving {@link
+ * An internal resolved representation of a factory function created by resolving `Provider`.
- * 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
+ * `Injector` internally only uses `ResolvedProvider`, `Provider` contains convenience provider
- * convenience provider syntax.
+ * 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
+ * Merges a list of ResolvedProviders into a list where each key is contained exactly once and
- * each key is contained exactly once and multi providers
+ * multi providers have been merged.
- * have been merged.
  */
 export function mergeResolvedReflectiveProviders(
     providers: ResolvedReflectiveProvider[],

packages/core/src/error_handler.ts

@@ -11,14 +11,13 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError}
 
 
 /**
- *
- * @description
  * Provides a hook for centralized exception handling.
  *
  * The default implementation of `ErrorHandler` prints error messages to the `console`. To
  * intercept error handling, write a custom exception handler that replaces this default as
  * appropriate for your app.
  *
+ * @usageNotes
  * ### Example
  *
  * ```
@@ -33,8 +32,6 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError}
  * })
  * class MyModule {}
  * ```
- *
- *
  */
 export class ErrorHandler {
   /**

packages/core/src/event_emitter.ts

@@ -11,6 +11,7 @@ import {Subject, Subscription} from 'rxjs';
 /**
  * Use by directives and components to emit custom Events.
  *
+ * @usageNotes
  * ### Examples
  *
  * In the following example, `Zippy` alternatively emits `open` and `close` events when its
@@ -49,6 +50,8 @@ import {Subject, Subscription} from 'rxjs';
  * <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
  *

packages/core/src/i18n/tokens.ts

@@ -15,6 +15,7 @@ import {InjectionToken} from '../di/injection_token';
  *
  * See the [i18n guide](guide/i18n#setting-up-locale) for more information.
  *
+ * @usageNotes
  * ### Example
  *
  * ```typescript
@@ -37,6 +38,7 @@ export const LOCALE_ID = new InjectionToken<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';

packages/core/src/linker/query_list.ts

@@ -27,6 +27,7 @@ import {getSymbolIterator} from '../util';
  *
  * NOTE: In the future this class will implement an `Observable` interface.
  *
+ * @usageNotes
  * ### Example
  * ```typescript
  * @Component({...})
@@ -34,7 +35,6 @@ import {getSymbolIterator} from '../util';
  *   @ViewChildren(Item) items:QueryList<Item>;
  * }
  * ```
- *
  */
 export class QueryList<T>/* implements Iterable<T> */ {
   public readonly dirty = true;

packages/core/src/linker/view_ref.ts

@@ -29,9 +29,10 @@ export abstract class ViewRef extends ChangeDetectorRef {
  *
  * Properties of elements in a View can change, but the structure (number and order) of elements in
  * a View cannot. Changing the structure of Elements can only be done by inserting, moving or
- * removing nested Views via a {@link ViewContainerRef}. Each View can contain many View Containers.
+ * removing nested Views via a `ViewContainerRef`. Each View can contain many View Containers.
  * <!-- /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 -->

packages/core/src/metadata/di.ts

@@ -16,6 +16,7 @@ import {makeParamDecorator, makePropDecorator} from '../util/decorators';
  * All components that are referenced in the `useValue` value (either directly
  * or in a nested array or map) will be added to the `entryComponents` property.
  *
+ * @usageNotes
  * ### Example
  * The following example shows how the router can populate the `entryComponents`
  * field of an NgModule based on the router configuration which refers
@@ -57,6 +58,7 @@ export interface AttributeDecorator {
    *
    * The directive can inject constant string literals of host element attributes.
    *
+   * @usageNotes
    * ### Example
    *
    * Suppose we have an `<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
+ * @see `ContentChildren`.
- * more information.
+ * @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,
+   * updated, and the changes observable of the query list will emit a new value.
-   * 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(

packages/core/src/metadata/directives.ts

@@ -16,25 +16,9 @@ import {ViewEncapsulation} from './view';
 
 /**
  * Type of the Directive decorator / constructor function.
- *
- *
  */
 export interface DirectiveDecorator {
   /**
-   * @usageNotes
-   *
-   * ```
-   * import {Directive} from '@angular/core';
-   *
-   * @Directive({
-   *   selector: 'my-directive',
-   * })
-   * export class MyDirective {
-   * }
-   * ```
-   *
-   * @description
-   *
    * Marks a class as an Angular directive and collects directive configuration
    * metadata.
    *
@@ -65,13 +49,24 @@ export interface DirectiveDecorator {
    * * **queries** -  configure queries that can be injected into the component
    * * **selector** - css selector that identifies this component in a template
    *
+   * @usageNotes
+   *
+   * ```
+   * import {Directive} from '@angular/core';
+   *
+   * @Directive({
+   *   selector: 'my-directive',
+   * })
+   * export class MyDirective {
+   * }
+   * ```
    *
    * @Annotation
    */
   (obj: Directive): TypeDecorator;
 
   /**
-   * See the {@link Directive} decorator.
+   * See the `Directive` decorator.
    */
   new (obj: Directive): Directive;
 }
@@ -92,7 +87,7 @@ export interface Directive {
    * - `:not(sub_selector)`: select only if the element does not match the `sub_selector`.
    * - `selector1, selector2`: select if either `selector1` or `selector2` matches.
    *
-   *
+   * @usageNotes
    * ### Example
    *
    * Suppose we have a directive with an `input[type=text]` selector.
@@ -124,6 +119,7 @@ export interface Directive {
    *
    * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`.
    *
+   * @usageNotes
    * ### Example
    *
    * The following example creates a component with two data-bound properties.
@@ -153,7 +149,6 @@ export interface Directive {
    * })
    * class App {}
    * ```
-   *
    */
   inputs?: string[];
 
@@ -169,6 +164,7 @@ export interface Directive {
    * - `directiveProperty` specifies the component property that emits events.
    * - `bindingProperty` specifies the DOM property the event handler is attached to.
    *
+   * @usageNotes
    * ### Example
    *
    * ```typescript
@@ -198,14 +194,17 @@ export interface Directive {
    *   everyFiveSeconds() { console.log('five seconds'); }
    * }
    * ```
-   *
    */
   outputs?: string[];
 
   /**
    * Specify the events, actions, properties and attributes related to the host element.
    *
-   * ## Host Listeners
+   * @usageNotes
+   * The key corresponds to the name of the event, property or attribute on the host to
+   * bind. The value is formatted differently depending upon the type of the binding.
+   *
+   * ### Host Listeners
    *
    * Specifies which DOM events a directive listens to via a set of `(event)` to `method`
    * key-value pairs:
@@ -220,8 +219,6 @@ export interface Directive {
    *
    * When writing a directive event binding, you can also refer to the $event local variable.
    *
-   * ### Example
-   *
    * The following example declares a directive that attaches a click listener to the button and
    * counts clicks.
    *
@@ -247,15 +244,13 @@ export interface Directive {
    * class App {}
    * ```
    *
-   * ## Host Property Bindings
+   * ### Host Property Bindings
    *
    * Specifies which DOM properties a directive updates.
    *
    * Angular automatically checks host property bindings during change detection.
    * If a binding changes, it will update the host element of the directive.
    *
-   * ### Example
-   *
    * The following example creates a directive that sets the `valid` and `invalid` classes
    * on the DOM element that has ngModel directive on it.
    *
@@ -282,12 +277,10 @@ export interface Directive {
    * }
    * ```
    *
-   * ## Attributes
+   * ### Attributes
    *
    * Specifies static attributes that should be propagated to a host element.
    *
-   * ### Example
-   *
    * In this example using `my-button` directive (ex.: `<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.
    *
-   *
+   * @usageNotes
-   * ## Simple Example
+   * ### Simple Example
    *
    * ```
    * @Directive({
@@ -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()}
+   * - `trigger()`
-   * - {@link state state()}
+   * - `state()`
-   * - {@link transition transition()}
+   * - `transition()`
-   * - {@link group group()}
+   * - `group()`
-   * - {@link sequence sequence()}
+   * - `sequence()`
-   * - {@link style style()}
+   * - `style()`
-   * - {@link animate animate()}
+   * - `animate()`
-   * - {@link keyframes keyframes()}
+   * - `keyframes()`
    */
   animations?: any[];
 
   /**
    * Specifies how the template and the styles should be encapsulated:
-   * - {@link ViewEncapsulation#Native `ViewEncapsulation.Native`} to use shadow roots - only works
+   * - `ViewEncapsulation.Native` to use shadow roots - only works if natively available on the
-   *   if natively available on the platform,
+   *   platform,
-   * - {@link ViewEncapsulation#Emulated `ViewEncapsulation.Emulated`} to use shimmed CSS that
+   * - `ViewEncapsulation.Emulated` to use shimmed CSS that emulates the native behavior,
-   *   emulates the native behavior,
+   * - `ViewEncapsulation.None` to use global CSS without any encapsulation.
-   * - {@link ViewEncapsulation#None `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
+   * Angular will create a `ComponentFactory` and store it in the
-   * {@link ComponentFactoryResolver}.
+   * `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 =

packages/core/src/render3/view_ref.ts

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

packages/core/src/zone/ng_zone.ts

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

packages/core/testing/src/fake_async.ts

@@ -33,7 +33,8 @@ export function resetFakeAsyncZone(): void {
  *
  * Can be used to wrap inject() calls.
  *
- * ## Example
+ * @usageNotes
+ * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *
@@ -56,7 +57,8 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
  * The microtasks queue is drained at the very start of this function and after any timer callback
  * has been executed.
  *
- * ## Example
+ * @usageNotes
+ * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *

packages/core/testing/src/fake_async_fallback.ts

@@ -43,7 +43,8 @@ let _inFakeAsyncCall = false;
  *
  * Can be used to wrap inject() calls.
  *
- * ## Example
+ * @usageNotes
+ * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *
@@ -110,7 +111,8 @@ function _getFakeAsyncZoneSpec(): any {
  * The microtasks queue is drained at the very start of this function and after any timer callback
  * has been executed.
  *
- * ## Example
+ * @usageNotes
+ * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *