diff --git a/packages/core/src/di/injectable.ts b/packages/core/src/di/injectable.ts
index 44f643113889e..663a03a2195a9 100644
--- a/packages/core/src/di/injectable.ts
+++ b/packages/core/src/di/injectable.ts
@@ -34,14 +34,15 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
  */
 export interface InjectableDecorator {
   /**
-   * @whatItDoes A marker metadata that marks a class as available to {@link Injector} for creation.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {}
    * ```
    *
    * @description
+   * A marker metadata that marks a class as available to {@link Injector} for creation.
+   *
    * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
diff --git a/packages/core/src/di/injector.ts b/packages/core/src/di/injector.ts
index db286b326e4d5..ba98456e357ff 100644
--- a/packages/core/src/di/injector.ts
+++ b/packages/core/src/di/injector.ts
@@ -39,14 +39,16 @@ export class NullInjector implements Injector {
 }
 
 /**
- * @whatItDoes Injector interface
- * @howToUse
+ * @usageNotes
  * ```
  * const injector: Injector = ...;
  * injector.get(...);
  * ```
  *
  * @description
+ *
+ * Concrete injectors implement this interface.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
diff --git a/packages/core/src/di/metadata.ts b/packages/core/src/di/metadata.ts
index b3f155d6c7089..bb283669cb835 100644
--- a/packages/core/src/di/metadata.ts
+++ b/packages/core/src/di/metadata.ts
@@ -20,8 +20,7 @@ import {EMPTY_ARRAY} from '../view/util';
  */
 export interface InjectDecorator {
   /**
-   * @whatItDoes A parameter decorator that specifies a dependency.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {
@@ -30,6 +29,8 @@ export interface InjectDecorator {
    * ```
    *
    * @description
+   * A parameter decorator that specifies a dependency.
+   *
    * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
@@ -72,9 +73,7 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
  */
 export interface OptionalDecorator {
   /**
-   * @whatItDoes A parameter metadata that marks a dependency as optional.
-   * {@link Injector} provides `null` if the dependency is not found.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {
@@ -83,6 +82,9 @@ export interface OptionalDecorator {
    * ```
    *
    * @description
+   * A parameter metadata that marks a dependency as optional.
+   * {@link Injector} provides `null` if the dependency is not found.
+   *
    * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
@@ -117,8 +119,7 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
  */
 export interface SelfDecorator {
   /**
-   * @whatItDoes Specifies that an {@link Injector} should retrieve a dependency only from itself.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {
@@ -127,6 +128,8 @@ export interface SelfDecorator {
    * ```
    *
    * @description
+   * Specifies that an {@link Injector} should retrieve a dependency only from itself.
+   *
    * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
@@ -162,8 +165,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
  */
 export interface SkipSelfDecorator {
   /**
-   * @whatItDoes Specifies that the dependency resolution should start from the parent injector.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {
@@ -172,6 +174,8 @@ export interface SkipSelfDecorator {
    * ```
    *
    * @description
+   * Specifies that the dependency resolution should start from the parent injector.
+   *
    * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
@@ -206,9 +210,7 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
  */
 export interface HostDecorator {
   /**
-   * @whatItDoes Specifies that an injector should retrieve a dependency from any injector until
-   * reaching the host element of the current component.
-   * @howToUse
+   * @usageNotes
    * ```
    * @Injectable()
    * class Car {
@@ -217,6 +219,9 @@ export interface HostDecorator {
    * ```
    *
    * @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 {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
    *
    * ### Example
diff --git a/packages/core/src/di/provider.ts b/packages/core/src/di/provider.ts
index 5326ad7355e07..9b22c062da02c 100644
--- a/packages/core/src/di/provider.ts
+++ b/packages/core/src/di/provider.ts
@@ -9,14 +9,15 @@
 import {Type} from '../type';
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value for a token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable(SomeModule, {useValue: 'someValue'})
  * class SomeClass {}
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -33,13 +34,14 @@ export interface ValueSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value for a token.
- * @howToUse
+ * @usageNotes
  * ```
  * const provider: ValueProvider = {provide: 'someToken', useValue: 'someValue'};
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -66,14 +68,15 @@ export interface ValueProvider extends ValueSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
- * @howToUse
+ * @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 {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -97,8 +100,7 @@ export interface StaticClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable()
  * class MyService {}
@@ -107,6 +109,8 @@ export interface StaticClassSansProvider {
  * ```
  *
  * @description
+ * Configures the `Injector` to return an instance of `useClass` for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -136,14 +140,15 @@ export interface StaticClassProvider extends StaticClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of a token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable(SomeModule, {deps: []})
  * class MyService {}
  * ```
  *
  * @description
+ * Configures the `Injector` to return an instance of a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -161,8 +166,7 @@ export interface ConstructorSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of a token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable()
  * class MyService {}
@@ -171,6 +175,8 @@ export interface ConstructorSansProvider {
  * ```
  *
  * @description
+ * Configures the `Injector` to return an instance of a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -197,14 +203,15 @@ export interface ConstructorProvider extends ConstructorSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value of another `useExisting` token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable(SomeModule, {useExisting: 'someOtherToken'})
  * class SomeClass {}
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value of another `useExisting` token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -221,13 +228,14 @@ export interface ExistingSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value of another `useExisting` token.
- * @howToUse
+ * @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 {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -254,9 +262,7 @@ export interface ExistingProvider extends ExistingSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
- * function.
- * @howToUse
+ * @usageNotes
  * ```
  * function serviceFactory() { ... }
  *
@@ -265,6 +271,8 @@ export interface ExistingProvider extends ExistingSansProvider {
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value by invoking a `useFactory` function.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -288,9 +296,7 @@ export interface FactorySansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
- * function.
- * @howToUse
+ * @usageNotes
  * ```
  * function serviceFactory() { ... }
  *
@@ -298,6 +304,8 @@ export interface FactorySansProvider {
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value by invoking a `useFactory` function.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -327,12 +335,12 @@ export interface FactoryProvider extends FactorySansProvider {
 }
 
 /**
- * @whatItDoes Describes how the {@link Injector} should be configured in a static way (Without
- * reflection).
- * @howToUse
+ * @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 {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * @stable
@@ -342,9 +350,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
 
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `Type` when `Type' is used
- * as token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable()
  * class MyService {}
@@ -353,6 +359,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
  * ```
  *
  * @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.
  * This form is a short form of `TypeProvider`;
@@ -368,9 +375,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
 export interface TypeProvider extends Type<any> {}
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useClass`
- * function.
- * @howToUse
+ * @usageNotes
  * ```
  *
  * class SomeClassImpl {}
@@ -380,6 +385,8 @@ export interface TypeProvider extends Type<any> {}
  * ```
  *
  * @description
+ * Configures the `Injector` to return a value by invoking a `useClass` function.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -396,8 +403,7 @@ export interface ClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
- * @howToUse
+ * @usageNotes
  * ```
  * @Injectable()
  * class MyService {}
@@ -406,6 +412,8 @@ export interface ClassSansProvider {
  * ```
  *
  * @description
+ * Configures the `Injector` to return an instance of `useClass` for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -435,11 +443,12 @@ export interface ClassProvider extends ClassSansProvider {
 }
 
 /**
- * @whatItDoes Describes how the {@link Injector} should be configured.
- * @howToUse
+ * @usageNotes
  * See {@link TypeProvider}, {@link ClassProvider}, {@link StaticProvider}.
  *
  * @description
+ * Describes how the `Injector` should be configured.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * @stable
diff --git a/packages/core/src/error_handler.ts b/packages/core/src/error_handler.ts
index c1266d1c57ca7..f961c4cc33aac 100644
--- a/packages/core/src/error_handler.ts
+++ b/packages/core/src/error_handler.ts
@@ -11,9 +11,9 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError}
 
 
 /**
- * @whatItDoes Provides a hook for centralized exception handling.
  *
  * @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
diff --git a/packages/core/src/metadata/di.ts b/packages/core/src/metadata/di.ts
index e12522be1258e..2fe51f32944d7 100644
--- a/packages/core/src/metadata/di.ts
+++ b/packages/core/src/metadata/di.ts
@@ -141,13 +141,13 @@ export abstract class Query {}
  */
 export interface ContentChildrenDecorator {
   /**
-   * @whatItDoes Configures a content query.
    *
-   * @howToUse
+   * @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
    * content DOM. Any time a child element is added, removed, or moved, the query list will be
@@ -203,13 +203,13 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
  */
 export interface ContentChildDecorator {
   /**
-   * @whatItDoes Configures a content query.
    *
-   * @howToUse
+   * @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
    * the content DOM. If the content DOM changes, and a new child matches the selector,
@@ -264,13 +264,13 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
  */
 export interface ViewChildrenDecorator {
   /**
-   * @whatItDoes Configures a view query.
    *
-   * @howToUse
+   * @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
    * view DOM. Any time a child element is added, removed, or moved, the query list will be updated,
@@ -323,13 +323,13 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator(
  */
 export interface ViewChildDecorator {
   /**
-   * @whatItDoes Configures a view query.
    *
-   * @howToUse
+   * @usageNotes
    *
    * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'}
    *
    * @description
+   * Configures a view query.
    *
    * You can use ViewChild to get the first element or the directive matching the selector from the
    * view DOM. If the view DOM changes, and a new child matches the selector,
diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts
index a534897e0e2cf..9c7fb21a3037a 100644
--- a/packages/core/src/metadata/directives.ts
+++ b/packages/core/src/metadata/directives.ts
@@ -21,10 +21,7 @@ import {ViewEncapsulation} from './view';
  */
 export interface DirectiveDecorator {
   /**
-   * @whatItDoes Marks a class as an Angular directive and collects directive configuration
-   * metadata.
-   *
-   * @howToUse
+   * @usageNotes
    *
    * ```
    * import {Directive} from '@angular/core';
@@ -38,6 +35,9 @@ export interface DirectiveDecorator {
    *
    * @description
    *
+   * Marks a class as an Angular directive and collects directive configuration
+   * metadata.
+   *
    * Directive decorator allows you to mark a class as an Angular directive and provide additional
    * metadata that determines how the directive should be processed, instantiated and used at
    * runtime.
@@ -410,14 +410,14 @@ export const Directive: DirectiveDecorator =
  */
 export interface ComponentDecorator {
   /**
-   * @whatItDoes Marks a class as an Angular component and collects component configuration
-   * metadata.
-   *
-   * @howToUse
+   * @usageNotes
    *
    * {@example core/ts/metadata/metadata.ts region='component'}
    *
    * @description
+   * Marks a class as an Angular component and collects component configuration
+   * metadata.
+   *
    * Component decorator allows you to mark a class as an Angular component and provide additional
    * metadata that determines how the component should be processed, instantiated and used at
    * runtime.
diff --git a/packages/core/src/metadata/lifecycle_hooks.ts b/packages/core/src/metadata/lifecycle_hooks.ts
index 6520bd50279f8..70046d97a2908 100644
--- a/packages/core/src/metadata/lifecycle_hooks.ts
+++ b/packages/core/src/metadata/lifecycle_hooks.ts
@@ -17,11 +17,12 @@ import {SimpleChange} from '../change_detection/change_detection_util';
 export interface SimpleChanges { [propName: string]: SimpleChange; }
 
 /**
- * @whatItDoes Lifecycle hook that is called when any data-bound property of a directive changes.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnChanges'}
  *
  * @description
+ * Lifecycle hook that is called when any data-bound property of a directive changes.
+ *
  * `ngOnChanges` is called right after the data-bound properties have been checked and before view
  * and content children are checked if at least one of them has changed.
  * The `changes` parameter contains the changed properties.
@@ -33,12 +34,13 @@ export interface SimpleChanges { [propName: string]: SimpleChange; }
 export interface OnChanges { ngOnChanges(changes: SimpleChanges): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called after data-bound properties of a directive are
- * initialized.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnInit'}
  *
  * @description
+ * Lifecycle hook that is called after data-bound properties of a directive are
+ * initialized.
+ *
  * `ngOnInit` is called right after the directive's data-bound properties have been checked for the
  * first time, and before any of its children have been checked. It is invoked only once when the
  * directive is instantiated.
@@ -50,11 +52,12 @@ export interface OnChanges { ngOnChanges(changes: SimpleChanges): void; }
 export interface OnInit { ngOnInit(): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called when Angular dirty checks a directive.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='DoCheck'}
  *
  * @description
+ * Lifecycle hook that is called when Angular dirty checks a directive.
+ *
  * `ngDoCheck` gets called to check the changes in the directives in addition to the default
  * algorithm. The default change detection algorithm looks for differences by comparing
  * bound-property values by reference across change detection runs.
@@ -73,11 +76,12 @@ export interface OnInit { ngOnInit(): void; }
 export interface DoCheck { ngDoCheck(): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called when a directive, pipe or service is destroyed.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnDestroy'}
  *
  * @description
+ * Lifecycle hook that is called when a directive, pipe or service is destroyed.
+ *
  * `ngOnDestroy` callback is typically used for any custom cleanup that needs to occur when the
  * instance is destroyed.
  *
@@ -89,12 +93,13 @@ export interface OnDestroy { ngOnDestroy(): void; }
 
 /**
  *
- * @whatItDoes Lifecycle hook that is called after a directive's content has been fully
- * initialized.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentInit'}
  *
  * @description
+ * Lifecycle hook that is called after a directive's content has been fully
+ * initialized.
+ *
  * See {@linkDocs guide/lifecycle-hooks#aftercontent "Lifecycle Hooks Guide"}.
  *
  * @stable
@@ -102,11 +107,12 @@ export interface OnDestroy { ngOnDestroy(): void; }
 export interface AfterContentInit { ngAfterContentInit(): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called after every check of a directive's content.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentChecked'}
  *
  * @description
+ * Lifecycle hook that is called after every check of a directive's content.
+ *
  * See {@linkDocs guide/lifecycle-hooks#aftercontent "Lifecycle Hooks Guide"}.
  *
  * @stable
@@ -114,12 +120,13 @@ export interface AfterContentInit { ngAfterContentInit(): void; }
 export interface AfterContentChecked { ngAfterContentChecked(): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called after a component's view has been fully
- * initialized.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewInit'}
  *
  * @description
+ * Lifecycle hook that is called after a component's view has been fully
+ * initialized.
+ *
  * See {@linkDocs guide/lifecycle-hooks#afterview "Lifecycle Hooks Guide"}.
  *
  * @stable
@@ -127,11 +134,12 @@ export interface AfterContentChecked { ngAfterContentChecked(): void; }
 export interface AfterViewInit { ngAfterViewInit(): void; }
 
 /**
- * @whatItDoes Lifecycle hook that is called after every check of a component's view.
- * @howToUse
+ * @usageNotes
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewChecked'}
  *
  * @description
+ * Lifecycle hook that is called after every check of a component's view.
+ *
  * See {@linkDocs guide/lifecycle-hooks#afterview "Lifecycle Hooks Guide"}.
  *
  * @stable
diff --git a/packages/core/src/type.ts b/packages/core/src/type.ts
index 72524fd2a8684..a6429bd9706d9 100644
--- a/packages/core/src/type.ts
+++ b/packages/core/src/type.ts
@@ -7,10 +7,10 @@
  */
 
 /**
- * @whatItDoes Represents a type that a Component or other object is instances of.
- *
  * @description
  *
+ * Represents a type that a Component or other object is instances of.
+ *
  * An example of a `Type` is `MyCustomComponent` class, which in JavaScript is be represented by
  * the `MyCustomComponent` constructor function.
  *
diff --git a/packages/core/src/version.ts b/packages/core/src/version.ts
index 0d5b462866d61..76534b37e8d2b 100644
--- a/packages/core/src/version.ts
+++ b/packages/core/src/version.ts
@@ -7,7 +7,7 @@
  */
 
 /**
- * @whatItDoes Represents the version of Angular
+ * @description Represents the version of Angular
  *
  * @stable
  */
diff --git a/packages/core/testing/src/test_bed.ts b/packages/core/testing/src/test_bed.ts
index 17e6fce535619..32f1470c453e5 100644
--- a/packages/core/testing/src/test_bed.ts
+++ b/packages/core/testing/src/test_bed.ts
@@ -49,9 +49,9 @@ export type TestModuleMetadata = {
 };
 
 /**
- * @whatItDoes Configures and initializes environment for unit testing and provides methods for
- * creating components and services in unit tests.
  * @description
+ * Configures and initializes environment for unit testing and provides methods for
+ * creating components and services in unit tests.
  *
  * TestBed is the primary api for writing unit tests for Angular applications and libraries.
  *