docs(upgrade): migrate deprecatd `@whatItDoes` tags (#23197)

These tags' contents  are now included in the `@description` tag.

PR Close #23197

packages/upgrade/src/common/downgrade_component.ts

@@ -19,21 +19,15 @@ interface Thenable<T> {
 }
 
 /**
- * @whatItDoes
+ * @description
+ *
+ * A helper function that allows an Angular component to be used from AngularJS.
  *
  * *Part of the [upgrade/static](api?query=upgrade%2Fstatic)
  * library for hybrid upgrade apps that support AoT compilation*
  *
- * Allows an Angular component to be used from AngularJS.
+ * This helper function returns a factory function to be used for registering
- *
+ * an AngularJS wrapper directive for "downgrading" an Angular component.
- * @description
- *
- * A helper function that returns a factory function to be used for registering an
- * AngularJS wrapper directive for "downgrading" an Angular component.
- *
- * The parameter contains information about the Component that is being downgraded:
- *
- * * `component: Type<any>`: The type of the Component that will be downgraded
  *
  * ### Examples
  *
@@ -49,6 +43,13 @@ interface Thenable<T> {
  *
  * {@example upgrade/static/ts/module.ts region="ng2-heroes-wrapper"}
  *
+ * @param info contains information about the Component that is being downgraded:
+ *
+ * * `component: Type<any>`: The type of the Component that will be downgraded
+ *
+ * @returns a factory function that can be used to register the component in an
+ * AngularJS module.
+ *
  * @experimental
  */
 export function downgradeComponent(info: {

packages/upgrade/src/common/downgrade_injectable.ts

@@ -10,22 +10,15 @@ import {Injector} from '@angular/core';
 import {INJECTOR_KEY} from './constants';
 
 /**
- * @whatItDoes
+ * @description
+ *
+ * A helper function to allow an Angular service to be accessible from AngularJS.
  *
  * *Part of the [upgrade/static](api?query=upgrade%2Fstatic)
  * library for hybrid upgrade apps that support AoT compilation*
  *
- * Allow an Angular service to be accessible from AngularJS.
+ * This helper function returns a factory function that provides access to the Angular
- *
+ * service identified by the `token` parameter.
- * @description
- *
- * Takes a `token` that identifies a service provided from Angular.
- *
- * Returns a [factory function](https://docs.angularjs.org/guide/di) that can be
- * used to register the service on an AngularJS module.
- *
- * The factory function provides access to the Angular service that
- * is identified by the `token` parameter.
  *
  * ### Examples
  *
@@ -49,6 +42,11 @@ import {INJECTOR_KEY} from './constants';
  *
  * {@example upgrade/static/ts/module.ts region="example-app"}
  *
+ * @param token an `InjectionToken` that identifies a service provided from Angular.
+ *
+ * @returns a [factory function](https://docs.angularjs.org/guide/di) that can be
+ * used to register the service on an AngularJS module.
+ *
  * @experimental
  */
 export function downgradeInjectable(token: any): Function {

packages/upgrade/src/static/upgrade_component.ts

@@ -27,16 +27,14 @@ class Bindings {
 }
 
 /**
- * @whatItDoes
+ * @description
+ *
+ * A helper class that allows an AngularJS component to be used from Angular.
  *
  * *Part of the [upgrade/static](api?query=upgrade%2Fstatic)
  * library for hybrid upgrade apps that support AoT compilation*
  *
- * Allows an AngularJS component to be used from Angular.
+ * This helper class should be used as a base class for creating Angular directives
- *
- * @description
- *
- * A helper class that should be used as a base class for creating Angular directives
  * that wrap AngularJS components that need to be "upgraded".
  *
  * ### Examples

packages/upgrade/src/static/upgrade_module.ts

@@ -17,13 +17,16 @@ import {NgAdapterInjector} from './util';
 
 
 /**
- * @whatItDoes
+ * @description
+ *
+ * An `NgModule`, which you import to provide AngularJS core services,
+ * and has an instance method used to bootstrap the hybrid upgrade application.
  *
  * *Part of the [upgrade/static](api?query=upgrade%2Fstatic)
  * library for hybrid upgrade apps that support AoT compilation*
  *
- * Allows AngularJS and Angular components to be used together inside a hybrid upgrade
+ * The `upgrade/static` package contains helpers that allow AngularJS and Angular components
- * application, which supports AoT compilation.
+ * to be used together inside a hybrid upgrade application, which supports AoT compilation.
  *
  * Specifically, the classes and functions in the `upgrade/static` module allow the following:
  * 1. Creation of an Angular directive that wraps and exposes an AngularJS component so
@@ -37,9 +40,9 @@ import {NgAdapterInjector} from './util';
  *    so that it can be injected into an AngularJS context. See {@link downgradeInjectable}.
  * 3. Bootstrapping of a hybrid Angular application which contains both of the frameworks
  *    coexisting in a single application. See the
- *    {@link UpgradeModule#example example} below.
+ *    {@link UpgradeModule#examples example} below.
  *
- * ## Mental Model
+ * ### Mental Model
  *
  * When reasoning about how a hybrid application works it is useful to have a mental model which
  * describes what is happening and explains what is happening at the lowest level.
@@ -65,25 +68,19 @@ import {NgAdapterInjector} from './util';
  *    a. This implies that the component bindings will always follow the semantics of the
  *       instantiation framework.
  *    b. The DOM attributes are parsed by the framework that owns the current template. So
- * attributes
+ *       attributes in AngularJS templates must use kebab-case, while AngularJS templates must
- *       in AngularJS templates must use kebab-case, while AngularJS templates must use camelCase.
+ *       use camelCase.
  *    c. However the template binding syntax will always use the Angular style, e.g. square
  *       brackets (`[...]`) for property binding.
  * 8. AngularJS is always bootstrapped first and owns the root component.
  * 9. The new application is running in an Angular zone, and therefore it no longer needs calls
- * to
+ *    to `$apply()`.
- *    `$apply()`.
  *
- * @description
+ * ### Core AngularJS services
- *
- * This class is an `NgModule`, which you import to provide AngularJS core services,
- * and has an instance method used to bootstrap the hybrid upgrade application.
- *
- * ## Core AngularJS services
  * Importing this {@link NgModule} will add providers for the core
  * [AngularJS services](https://docs.angularjs.org/api/ng/service) to the root injector.
  *
- * ## Bootstrap
+ * ### Bootstrap
  * The runtime instance of this class contains a {@link UpgradeModule#bootstrap `bootstrap()`}
  * method, which you use to bootstrap the top level AngularJS module onto an element in the
  * DOM for the hybrid upgrade app.
@@ -94,9 +91,6 @@ import {NgAdapterInjector} from './util';
  *
  * ### Examples
  *
- * `import {UpgradeModule} from '@angular/upgrade/static';`
- *
- * ## Example
  * Import the {@link UpgradeModule} into your top level {@link NgModule Angular `NgModule`}.
  *
  * {@example upgrade/static/ts/module.ts region='ng2-module'}
@@ -109,7 +103,7 @@ import {NgAdapterInjector} from './util';
  *
  * {@a upgrading-an-angular-1-service}
  *
- * ## Upgrading an AngularJS service
+ * ### Upgrading an AngularJS service
  *
  * There is no specific API for upgrading an AngularJS service. Instead you should just follow the
  * following recipe: