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

These tags' contents are now included in the `@description` tag. PR Close #23197
2018-04-05 16:39:51 +01:00 · 2018-04-05 16:39:51 +01:00 · 9d9fb607cd
parent 5dc50e4688
commit 9d9fb607cd
4 changed files with 40 additions and 49 deletions
--- a/packages/upgrade/src/common/downgrade_component.ts
+++ b/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.
- *
- * @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
+ * This helper function returns a factory function to be used for registering
+ * an AngularJS wrapper directive for "downgrading" an Angular component.
 *
 * ### 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: {
--- a/packages/upgrade/src/common/downgrade_injectable.ts
+++ b/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.
- *
- * @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.
+ * This helper function returns a factory function that provides access to the Angular
+ * service 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 {
--- a/packages/upgrade/src/static/upgrade_component.ts
+++ b/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.
- *
- * @description
- *
- * A helper class that should be used as a base class for creating Angular directives
+ * This helper class should be used as a base class for creating Angular directives
 * that wrap AngularJS components that need to be "upgraded".
 *
 * ### Examples
--- a/packages/upgrade/src/static/upgrade_module.ts
+++ b/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
- * application, which supports AoT compilation.
+ * The `upgrade/static` package contains helpers that allow AngularJS and Angular components
+ * 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
- *       in AngularJS templates must use kebab-case, while AngularJS templates must use camelCase.
+ *       attributes in AngularJS templates must use kebab-case, while AngularJS templates must
+ *       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
- *    `$apply()`.
+ *    to `$apply()`.
 *
- * @description
- *
- * 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
+ * ### 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: