From f66f408b041eca0641446c1799cc575ffa3d49b2 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 5 Apr 2018 11:38:57 +0100 Subject: [PATCH] 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 | 14 ++++------ .../src/directives/router_link_active.ts | 6 ----- .../router/src/directives/router_outlet.ts | 2 +- packages/router/src/interfaces.ts | 10 +++---- packages/router/src/router_module.ts | 6 +++-- packages/router/src/router_preloader.ts | 2 +- packages/router/src/router_state.ts | 26 ++++++++++--------- packages/router/src/url_tree.ts | 26 +++++++++---------- .../testing/src/router_testing_module.ts | 16 ++++++------ packages/router/upgrade/src/upgrade.ts | 2 +- 10 files changed, 52 insertions(+), 58 deletions(-) diff --git a/packages/router/src/directives/router_link.ts b/packages/router/src/directives/router_link.ts index abf0bcb311..2544f46de3 100644 --- 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: - * `link to user component` - * * @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: * `link to user component` * * If you use dynamic values to generate the link, you can pass an array of path diff --git a/packages/router/src/directives/router_link_active.ts b/packages/router/src/directives/router_link_active.ts index c6f7242058..95a190fcb9 100644 --- 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 - * - * ``` - * Bob - * ``` - * * @description * * The RouterLinkActive directive lets you add a CSS class to an element when the link's route diff --git a/packages/router/src/directives/router_outlet.ts b/packages/router/src/directives/router_outlet.ts index 01b1a5e85d..f29bf6e8e0 100644 --- 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 * * ``` * diff --git a/packages/router/src/interfaces.ts b/packages/router/src/interfaces.ts index 6d3932034d..6864a6e224 100644 --- 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 { /** * @whatItDoes Interface that class can implement to be a data provider. * - * @howToUse + * @description * * ``` * class Backend { @@ -315,7 +315,7 @@ export interface Resolve { * @whatItDoes Interface that a class can implement to be a guard deciding if a children can be * loaded. * - * @howToUse + * @description * * ``` * class UserToken {} diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts index 418b0be4a9..126600a0f6 100644 --- 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({ diff --git a/packages/router/src/router_preloader.ts b/packages/router/src/router_preloader.ts index f1191475b2..aceb6c3483 100644 --- 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}) diff --git a/packages/router/src/router_state.ts b/packages/router/src/router_state.ts index 934c8be3d2..be191a3262 100644 --- 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 { diff --git a/packages/router/src/url_tree.ts b/packages/router/src/url_tree.ts index 712da6eb17..8ff9345858 100644 --- 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 { diff --git a/packages/router/testing/src/router_testing_module.ts b/packages/router/testing/src/router_testing_module.ts index 75cd435a8c..511405c9bd 100644 --- 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({ diff --git a/packages/router/upgrade/src/upgrade.ts b/packages/router/upgrade/src/upgrade.ts index c76fbabb1a..62570c1b61 100644 --- 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({