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

These have been converted to `@usageNotes` or included in the
`@description` tag.

PR Close #23187

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

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

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>

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 {}

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({

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})

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> {

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 {

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({

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({