docs(router): migrate deprecated `@howToUse` tags (#23187)

These have been converted to `@usageNotes` or included in the `@description` tag. PR Close #23187
2018-04-05 11:38:57 +01:00 · 2018-04-05 11:38:57 +01:00 · f66f408b04
parent 92821e338b
commit f66f408b04
10 changed files with 52 additions and 58 deletions
--- a/packages/router/src/directives/router_link.ts
+++ b/packages/router/src/directives/router_link.ts
@ -20,19 +20,15 @@ import {UrlTree} from '../url_tree';
 /**
 * @whatItDoes Lets you link to specific parts of your app.
 *
- * @howToUse
- *
- * Consider the following route configuration:
- * `[{ path: 'user/:name', component: UserCmp }]`
- *
- * When linking to this `user/:name` route, you can write:
- * `<a routerLink='/user/bob'>link to user component</a>`
- *
 * @description
 *
 * The RouterLink directives let you link to specific parts of your app.
 *
- * When the link is static, you can use the directive as follows:
+ * Consider the following route configuration:
+ * `[{ path: 'user/:name', component: UserCmp }]`.
+ * When linking to this `user/:name` route, you use the `RouterLink` directive.
+ *
+ * If the link is static, you can use the directive as follows:
 * `<a routerLink="/user/bob">link to user component</a>`
 *
 * If you use dynamic values to generate the link, you can pass an array of path
--- a/packages/router/src/directives/router_link_active.ts
+++ b/packages/router/src/directives/router_link_active.ts
@ -18,12 +18,6 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
 /**
 * @whatItDoes Lets you add a CSS class to an element when the link's route becomes active.
 *
- * @howToUse
- *
- * ```
- * <a routerLink="/user/bob" routerLinkActive="active-link">Bob</a>
- * ```
- *
 * @description
 *
 * The RouterLinkActive directive lets you add a CSS class to an element when the link's route
--- a/packages/router/src/directives/router_outlet.ts
+++ b/packages/router/src/directives/router_outlet.ts
@ -16,7 +16,7 @@ import {PRIMARY_OUTLET} from '../shared';
 * @whatItDoes Acts as a placeholder that Angular dynamically fills based on the current router
 * state.
 *
- * @howToUse
+ * @description
 *
 * ```
 * <router-outlet></router-outlet>
--- a/packages/router/src/interfaces.ts
+++ b/packages/router/src/interfaces.ts
@ -16,7 +16,7 @@ import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state';
 * @whatItDoes Interface that a class can implement to be a guard deciding if a route can be
 * activated.
 *
- * @howToUse
+ * @description
 *
 * ```
 * class UserToken {}
@ -87,7 +87,7 @@ export interface CanActivate {
 * @whatItDoes Interface that a class can implement to be a guard deciding if a child route can be
 * activated.
 *
- * @howToUse
+ * @description
 *
 * ```
 * class UserToken {}
@ -168,7 +168,7 @@ export interface CanActivateChild {
 * @whatItDoes Interface that a class can implement to be a guard deciding if a route can be
 * deactivated.
 *
- * @howToUse
+ * @description
 *
 * ```
 * class UserToken {}
@ -242,7 +242,7 @@ export interface CanDeactivate<T> {
 /**
 * @whatItDoes Interface that class can implement to be a data provider.
 *
- * @howToUse
+ * @description
 *
 * ```
 * class Backend {
@ -315,7 +315,7 @@ export interface Resolve<T> {
 * @whatItDoes Interface that a class can implement to be a guard deciding if a children can be
 * loaded.
 *
- * @howToUse
+ * @description
 *
 * ```
 * class UserToken {}
--- a/packages/router/src/router_module.ts
+++ b/packages/router/src/router_module.ts
@ -73,7 +73,7 @@ export function routerNgProbeToken() {
 /**
 * @whatItDoes Adds router directives and providers.
 *
- * @howToUse
+ * @usageNotes
 *
 * RouterModule can be imported multiple times: once per lazily-loaded bundle.
 * Since the router deals with a global shared resource--location, we cannot have
@ -195,7 +195,9 @@ export function provideForRootGuard(router: Router): any {
 /**
 * @whatItDoes Registers routes.
 *
- * @howToUse
+ * @description
+ *
+ * ### Example
 *
 * ```
 * @NgModule({
--- a/packages/router/src/router_preloader.ts
+++ b/packages/router/src/router_preloader.ts
@ -28,7 +28,7 @@ export abstract class PreloadingStrategy {
 /**
 * @whatItDoes Provides a preloading strategy that preloads all modules as quickly as possible.
 *
- * @howToUse
+ * @description
 *
 * ```
 * RouteModule.forRoot(ROUTES, {preloadingStrategy: PreloadAllModules})
--- a/packages/router/src/router_state.ts
+++ b/packages/router/src/router_state.ts
@ -21,7 +21,12 @@ import {Tree, TreeNode} from './utils/tree';
 /**
 * @whatItDoes Represents the state of the router.
 *
- * @howToUse
+ * @description
+ *
+ * RouterState is a tree of activated routes. Every node in this tree knows about the "consumed" URL
+ * segments, the extracted parameters, and the resolved data.
+ *
+ * ### Example
 *
 * ```
 * @Component({templateUrl:'template.html'})
@ -36,10 +41,6 @@ import {Tree, TreeNode} from './utils/tree';
 * }
 * ```
 *
- * @description
- * RouterState is a tree of activated routes. Every node in this tree knows about the "consumed" URL
- * segments, the extracted parameters, and the resolved data.
- *
 * See {@link ActivatedRoute} for more information.
 *
 * @stable
@ -88,7 +89,7 @@ export function createEmptyStateSnapshot(
 * outlet.
 * An `ActivatedRoute` can also be used to traverse the router state tree.
 *
- * @howToUse
+ * @description
 *
 * ```
 * @Component({...})
@ -233,7 +234,7 @@ function flattenInherited(pathFromRoot: ActivatedRouteSnapshot[]): Inherited {
 * at a particular moment in time. ActivatedRouteSnapshot can also be used to traverse the router
 * state tree.
 *
- * @howToUse
+ * @description
 *
 * ```
 * @Component({templateUrl:'./my-component.html'})
@ -328,7 +329,12 @@ export class ActivatedRouteSnapshot {
 /**
 * @whatItDoes Represents the state of the router at a moment in time.
 *
- * @howToUse
+ * @description
+ *
+ * RouterStateSnapshot is a tree of activated route snapshots. Every node in this tree knows about
+ * the "consumed" URL segments, the extracted parameters, and the resolved data.
+ *
+ * ### Example
 *
 * ```
 * @Component({templateUrl:'template.html'})
@ -344,10 +350,6 @@ export class ActivatedRouteSnapshot {
 * }
 * ```
 *
- * @description
- * RouterStateSnapshot is a tree of activated route snapshots. Every node in this tree knows about
- * the "consumed" URL segments, the extracted parameters, and the resolved data.
- *
 * @stable
 */
 export class RouterStateSnapshot extends Tree<ActivatedRouteSnapshot> {
--- a/packages/router/src/url_tree.ts
+++ b/packages/router/src/url_tree.ts
@ -76,7 +76,13 @@ function containsSegmentGroupHelper(
 /**
 * @whatItDoes Represents the parsed URL.
 *
- * @howToUse
+ * @description
+ *
+ * Since a router state is a tree, and the URL is nothing but a serialized state, the URL is a
+ * serialized tree.
+ * UrlTree is a data structure that provides a lot of affordances in dealing with URLs
+ *
+ * ### Example
 *
 * ```
 * @Component({templateUrl:'template.html'})
@ -94,12 +100,6 @@ function containsSegmentGroupHelper(
 * }
 * ```
 *
- * @description
- *
- * Since a router state is a tree, and the URL is nothing but a serialized state, the URL is a
- * serialized tree.
- * UrlTree is a data structure that provides a lot of affordances in dealing with URLs
- *
 * @stable
 */
 export class UrlTree {
@ -163,7 +163,12 @@ export class UrlSegmentGroup {
 /**
 * @whatItDoes Represents a single URL segment.
 *
- * @howToUse
+ * @description
+ *
+ * A UrlSegment is a part of a URL between the two slashes. It contains a path and the matrix
+ * parameters associated with the segment.
+ *
+ * ## Example
 *
 * ```
 * @Component({templateUrl:'template.html'})
@ -178,11 +183,6 @@ export class UrlSegmentGroup {
 * }
 * ```
 *
- * @description
- *
- * A UrlSegment is a part of a URL between the two slashes. It contains a path and the matrix
- * parameters associated with the segment.
- *
 * @stable
 */
 export class UrlSegment {
--- a/packages/router/testing/src/router_testing_module.ts
+++ b/packages/router/testing/src/router_testing_module.ts
@ -16,7 +16,7 @@ import {ChildrenOutletContexts, ExtraOptions, NoPreloading, PreloadingStrategy,
 /**
 * @whatItDoes Allows to simulate the loading of ng modules in tests.
 *
- * @howToUse
+ * @description
 *
 * ```
 * const loader = TestBed.get(NgModuleFactoryLoader);
@ -133,7 +133,13 @@ export function setupTestingRouter(
 /**
 * @whatItDoes Sets up the router to be used for testing.
 *
- * @howToUse
+ * @description
+ *
+ * The modules sets up the router to be used for testing.
+ * It provides spy implementations of {@link Location}, {@link LocationStrategy}, and {@link
+ * NgModuleFactoryLoader}.
+ *
+ * ### Example
 *
 * ```
 * beforeEach(() => {
@ -147,12 +153,6 @@ export function setupTestingRouter(
 * });
 * ```
 *
- * @description
- *
- * The modules sets up the router to be used for testing.
- * It provides spy implementations of {@link Location}, {@link LocationStrategy}, and {@link
- * NgModuleFactoryLoader}.
- *
 * @stable
 */
@NgModule({
--- a/packages/router/upgrade/src/upgrade.ts
+++ b/packages/router/upgrade/src/upgrade.ts
@ -16,7 +16,7 @@ import {UpgradeModule} from '@angular/upgrade/static';
 * @whatItDoes Creates an initializer that in addition to setting up the Angular
 * router sets up the ngRoute integration.
 *
- * @howToUse
+ * @description
 *
 * ```
 * @NgModule({