docs(core): migrate `@whatItDoes` tags to the description (#23185)

We get the overview for the doc by splitting off the first
paragraph.

PR Close #23185

packages/core/src/di/injectable.ts

@@ -34,7 +34,6 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
  */
 export interface InjectableDecorator {
   /**
-   * @whatItDoes A marker metadata that marks a class as available to {@link Injector} for creation.
    * @usageNotes
    * ```
    * @Injectable()
@@ -42,6 +41,8 @@ export interface InjectableDecorator {
    * ```
    *
    * @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

packages/core/src/di/injector.ts

@@ -39,7 +39,6 @@ export class NullInjector implements Injector {
 }
 
 /**
- * @whatItDoes Injector interface
  * @usageNotes
  * ```
  * const injector: Injector = ...;
@@ -47,6 +46,9 @@ export class NullInjector implements Injector {
  * ```
  *
  * @description
+ *
+ * Concrete injectors implement this interface.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example

packages/core/src/di/metadata.ts

@@ -20,7 +20,6 @@ import {EMPTY_ARRAY} from '../view/util';
  */
 export interface InjectDecorator {
   /**
-   * @whatItDoes A parameter decorator that specifies a dependency.
    * @usageNotes
    * ```
    * @Injectable()
@@ -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,8 +73,6 @@ 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.
    * @usageNotes
    * ```
    * @Injectable()
@@ -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,7 +119,6 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
  */
 export interface SelfDecorator {
   /**
-   * @whatItDoes Specifies that an {@link Injector} should retrieve a dependency only from itself.
    * @usageNotes
    * ```
    * @Injectable()
@@ -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,7 +165,6 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
  */
 export interface SkipSelfDecorator {
   /**
-   * @whatItDoes Specifies that the dependency resolution should start from the parent injector.
    * @usageNotes
    * ```
    * @Injectable()
@@ -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,8 +210,6 @@ 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.
    * @usageNotes
    * ```
    * @Injectable()
@@ -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

packages/core/src/di/provider.ts

@@ -9,7 +9,6 @@
 import {Type} from '../type';
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value for a token.
  * @usageNotes
  * ```
  * @Injectable(SomeModule, {useValue: 'someValue'})
@@ -17,6 +16,8 @@ import {Type} from '../type';
  * ```
  *
  * @description
+ * Configures the {@link 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.
  * @usageNotes
  * ```
  * const provider: ValueProvider = {provide: 'someToken', useValue: 'someValue'};
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return a value for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -66,7 +68,6 @@ export interface ValueProvider extends ValueSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
  * @usageNotes
  * ```
  * @Injectable(SomeModule, {useClass: MyService, deps: []})
@@ -74,6 +75,8 @@ export interface ValueProvider extends ValueSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return an instance of `useClass` for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -97,7 +100,6 @@ export interface StaticClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
  * @usageNotes
  * ```
  * @Injectable()
@@ -107,6 +109,8 @@ export interface StaticClassSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return an instance of `useClass` for a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -136,7 +140,6 @@ export interface StaticClassProvider extends StaticClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of a token.
  * @usageNotes
  * ```
  * @Injectable(SomeModule, {deps: []})
@@ -144,6 +147,8 @@ export interface StaticClassProvider extends StaticClassSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return an instance of a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -161,7 +166,6 @@ export interface ConstructorSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of a token.
  * @usageNotes
  * ```
  * @Injectable()
@@ -171,6 +175,8 @@ export interface ConstructorSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return an instance of a token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -197,7 +203,6 @@ export interface ConstructorProvider extends ConstructorSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value of another `useExisting` token.
  * @usageNotes
  * ```
  * @Injectable(SomeModule, {useExisting: 'someOtherToken'})
@@ -205,6 +210,8 @@ export interface ConstructorProvider extends ConstructorSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link 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.
  * @usageNotes
  * ```
  * const provider: ExistingProvider = {provide: 'someToken', useExisting: 'someOtherToken'};
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return a value of another `useExisting` token.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -254,8 +262,6 @@ export interface ExistingProvider extends ExistingSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
- * function.
  * @usageNotes
  * ```
  * function serviceFactory() { ... }
@@ -265,6 +271,8 @@ export interface ExistingProvider extends ExistingSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return a value by invoking a `useFactory` function.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -288,8 +296,6 @@ export interface FactorySansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
- * function.
  * @usageNotes
  * ```
  * function serviceFactory() { ... }
@@ -298,6 +304,8 @@ export interface FactorySansProvider {
  * ```
  *
  * @description
+ * Configures the {@link 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).
  * @usageNotes
  * See {@link ValueProvider}, {@link ExistingProvider}, {@link FactoryProvider}.
  *
  * @description
+ * Describes how the {@link Injector} should be configured in a static way (Without reflection).
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * @stable
@@ -342,8 +350,6 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
 
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `Type` when `Type' is used
- * as token.
  * @usageNotes
  * ```
  * @Injectable()
@@ -353,6 +359,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
  * ```
  *
  * @description
+ * Configures the {@link 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,8 +375,6 @@ 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.
  * @usageNotes
  * ```
  *
@@ -380,6 +385,8 @@ export interface TypeProvider extends Type<any> {}
  * ```
  *
  * @description
+ * Configures the {@link Injector} to return a value by invoking a `useClass` function.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * ### Example
@@ -396,7 +403,6 @@ export interface ClassSansProvider {
 }
 
 /**
- * @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
  * @usageNotes
  * ```
  * @Injectable()
@@ -406,6 +412,8 @@ export interface ClassSansProvider {
  * ```
  *
  * @description
+ * Configures the {@link 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.
  * @usageNotes
  * See {@link TypeProvider}, {@link ClassProvider}, {@link StaticProvider}.
  *
  * @description
+ * Describes how the {@link Injector} should be configured.
+ *
  * For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
  *
  * @stable

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

packages/core/src/metadata/di.ts

@@ -141,13 +141,13 @@ export abstract class Query {}
  */
 export interface ContentChildrenDecorator {
   /**
-   * @whatItDoes Configures a content query.
    *
    * @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.
    *
    * @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.
    *
    * @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.
    *
    * @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,

packages/core/src/metadata/directives.ts

@@ -21,9 +21,6 @@ import {ViewEncapsulation} from './view';
  */
 export interface DirectiveDecorator {
   /**
-   * @whatItDoes Marks a class as an Angular directive and collects directive configuration
-   * metadata.
-   *
    * @usageNotes
    *
    * ```
@@ -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.
-   *
    * @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.

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

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

packages/core/src/version.ts

@@ -7,7 +7,7 @@
  */
 
 /**
- * @whatItDoes Represents the version of Angular
+ * @description Represents the version of Angular
  *
  * @stable
  */

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