From 31b90436b4c9bd806c2afbd2eb526331758ca6fc Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 5 Apr 2018 11:51:21 +0100 Subject: [PATCH] docs(router): migrate deprecated `@whatItDoes` tags (#23187) The first line of the description is now used as an overview. PR Close #23187 --- packages/router/src/config.ts | 41 ++++++++--- packages/router/src/directives/router_link.ts | 8 +-- .../src/directives/router_link_active.ts | 5 +- .../router/src/directives/router_outlet.ts | 5 +- packages/router/src/events.ts | 72 ++++++++++++++----- packages/router/src/interfaces.ts | 24 +++---- packages/router/src/route_reuse_strategy.ts | 8 ++- packages/router/src/router.ts | 13 ++-- packages/router/src/router_module.ts | 27 ++++--- packages/router/src/router_preloader.ts | 12 ++-- packages/router/src/router_state.ts | 26 ++++--- packages/router/src/shared.ts | 4 +- packages/router/src/url_handling_strategy.ts | 4 +- packages/router/src/url_tree.ts | 22 +++--- .../testing/src/router_testing_module.ts | 8 +-- packages/router/upgrade/src/upgrade.ts | 10 +-- 16 files changed, 184 insertions(+), 105 deletions(-) diff --git a/packages/router/src/config.ts b/packages/router/src/config.ts index 6c220759b3..b4ed625587 100644 --- a/packages/router/src/config.ts +++ b/packages/router/src/config.ts @@ -12,9 +12,10 @@ import {PRIMARY_OUTLET} from './shared'; import {UrlSegment, UrlSegmentGroup} from './url_tree'; /** - * @whatItDoes Represents router configuration. - * * @description + * + * Represents router configuration. + * * `Routes` is an array of route configurations. Each one has the following properties: * * - `path` is a string that uses the route matcher DSL. @@ -255,7 +256,7 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; export type Routes = Route[]; /** - * @whatItDoes Represents the results of the URL matching. + * @description Represents the results of the URL matching. * * * `consumed` is an array of the consumed URL segments. * * `posParams` is a map of positional parameters. @@ -267,10 +268,10 @@ export type UrlMatchResult = { }; /** - * @whatItDoes A function matching URLs - * * @description * + * A function matching URLs + * * A custom URL matcher can be provided when a combination of `path` and `pathMatch` isn't * expressive enough. * @@ -290,7 +291,10 @@ export type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: UrlMatchResult; /** - * @whatItDoes Represents the static data associated with a particular route. + * @description + * + * Represents the static data associated with a particular route. + * * See {@link Routes} for more details. * @stable */ @@ -299,7 +303,10 @@ export type Data = { }; /** - * @whatItDoes Represents the resolved data associated with a particular route. + * @description + * + * Represents the resolved data associated with a particular route. + * * See {@link Routes} for more details. * @stable */ @@ -308,7 +315,10 @@ export type ResolveData = { }; /** - * @whatItDoes The type of `loadChildren`. + * @description + * + * The type of `loadChildren`. + * * See {@link Routes} for more details. * @stable */ @@ -316,21 +326,30 @@ export type LoadChildrenCallback = () => Type| NgModuleFactory| Promise>| Observable>; /** - * @whatItDoes The type of `loadChildren`. + * @description + * + * The type of `loadChildren`. + * * See {@link Routes} for more details. * @stable */ export type LoadChildren = string | LoadChildrenCallback; /** - * @whatItDoes The type of `queryParamsHandling`. + * @description + * + * The type of `queryParamsHandling`. + * * See {@link RouterLink} for more details. * @stable */ export type QueryParamsHandling = 'merge' | 'preserve' | ''; /** - * @whatItDoes The type of `runGuardsAndResolvers`. + * @description + * + * The type of `runGuardsAndResolvers`. + * * See {@link Routes} for more details. * @experimental */ diff --git a/packages/router/src/directives/router_link.ts b/packages/router/src/directives/router_link.ts index 2544f46de3..ed9472c1ca 100644 --- a/packages/router/src/directives/router_link.ts +++ b/packages/router/src/directives/router_link.ts @@ -18,11 +18,9 @@ import {UrlTree} from '../url_tree'; /** - * @whatItDoes Lets you link to specific parts of your app. - * * @description * - * The RouterLink directives let you link to specific parts of your app. + * Lets you link to specific routes in your app. * * Consider the following route configuration: * `[{ path: 'user/:name', component: UserCmp }]`. @@ -154,7 +152,9 @@ export class RouterLink { } /** - * @whatItDoes Lets you link to specific parts of your app. + * @description + * + * Lets you link to specific routes in your app. * * See {@link RouterLink} for more information. * diff --git a/packages/router/src/directives/router_link_active.ts b/packages/router/src/directives/router_link_active.ts index 95a190fcb9..3aa62c2b5b 100644 --- a/packages/router/src/directives/router_link_active.ts +++ b/packages/router/src/directives/router_link_active.ts @@ -16,11 +16,12 @@ import {RouterLink, RouterLinkWithHref} from './router_link'; /** - * @whatItDoes Lets you add a CSS class to an element when the link's route becomes active. * * @description * - * The RouterLinkActive directive lets you add a CSS class to an element when the link's route + * Lets you add a CSS class to an element when the link's route becomes active. + * + * This directive lets you add a CSS class to an element when the link's route * becomes active. * * Consider the following example: diff --git a/packages/router/src/directives/router_outlet.ts b/packages/router/src/directives/router_outlet.ts index f29bf6e8e0..f09282faeb 100644 --- a/packages/router/src/directives/router_outlet.ts +++ b/packages/router/src/directives/router_outlet.ts @@ -13,11 +13,10 @@ import {ActivatedRoute} from '../router_state'; import {PRIMARY_OUTLET} from '../shared'; /** - * @whatItDoes Acts as a placeholder that Angular dynamically fills based on the current router - * state. - * * @description * + * Acts as a placeholder that Angular dynamically fills based on the current router state. + * * ``` * * diff --git a/packages/router/src/events.ts b/packages/router/src/events.ts index 67e1508499..887efa455d 100644 --- a/packages/router/src/events.ts +++ b/packages/router/src/events.ts @@ -10,7 +10,9 @@ import {Route} from './config'; import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state'; /** - * @whatItDoes Identifies the trigger of the navigation. + * @description + * + * Identifies the trigger of the navigation. * * * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`. * * 'popstate'--triggered by a popstate event @@ -21,7 +23,9 @@ import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state'; export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange'; /** - * @whatItDoes Base for events the Router goes through, as opposed to events tied to a specific + * @description + * + * Base for events the Router goes through, as opposed to events tied to a specific * Route. `RouterEvent`s will only be fired one time for any given navigation. * * Example: @@ -47,7 +51,9 @@ export class RouterEvent { } /** - * @whatItDoes Represents an event triggered when a navigation starts. + * @description + * + * Represents an event triggered when a navigation starts. * * @stable */ @@ -94,7 +100,9 @@ export class NavigationStart extends RouterEvent { } /** - * @whatItDoes Represents an event triggered when a navigation ends successfully. + * @description + * + * Represents an event triggered when a navigation ends successfully. * * @stable */ @@ -116,7 +124,9 @@ export class NavigationEnd extends RouterEvent { } /** - * @whatItDoes Represents an event triggered when a navigation is canceled. + * @description + * + * Represents an event triggered when a navigation is canceled. * * @stable */ @@ -136,7 +146,9 @@ export class NavigationCancel extends RouterEvent { } /** - * @whatItDoes Represents an event triggered when a navigation fails due to an unexpected error. + * @description + * + * Represents an event triggered when a navigation fails due to an unexpected error. * * @stable */ @@ -158,7 +170,9 @@ export class NavigationError extends RouterEvent { } /** - * @whatItDoes Represents an event triggered when routes are recognized. + * @description + * + * Represents an event triggered when routes are recognized. * * @stable */ @@ -182,7 +196,9 @@ export class RoutesRecognized extends RouterEvent { } /** - * @whatItDoes Represents the start of the Guard phase of routing. + * @description + * + * Represents the start of the Guard phase of routing. * * @experimental */ @@ -205,7 +221,9 @@ export class GuardsCheckStart extends RouterEvent { } /** - * @whatItDoes Represents the end of the Guard phase of routing. + * @description + * + * Represents the end of the Guard phase of routing. * * @experimental */ @@ -230,7 +248,9 @@ export class GuardsCheckEnd extends RouterEvent { } /** - * @whatItDoes Represents the start of the Resolve phase of routing. The timing of this + * @description + * + * Represents the start of the Resolve phase of routing. The timing of this * event may change, thus it's experimental. In the current iteration it will run * in the "resolve" phase whether there's things to resolve or not. In the future this * behavior may change to only run when there are things to be resolved. @@ -256,7 +276,9 @@ export class ResolveStart extends RouterEvent { } /** - * @whatItDoes Represents the end of the Resolve phase of routing. See note on + * @description + * + * Represents the end of the Resolve phase of routing. See note on * {@link ResolveStart} for use of this experimental API. * * @experimental @@ -280,7 +302,9 @@ export class ResolveEnd extends RouterEvent { } /** - * @whatItDoes Represents an event triggered before lazy loading a route config. + * @description + * + * Represents an event triggered before lazy loading a route config. * * @experimental */ @@ -292,7 +316,9 @@ export class RouteConfigLoadStart { } /** - * @whatItDoes Represents an event triggered when a route has been lazy loaded. + * @description + * + * Represents an event triggered when a route has been lazy loaded. * * @experimental */ @@ -304,7 +330,9 @@ export class RouteConfigLoadEnd { } /** - * @whatItDoes Represents the start of end of the Resolve phase of routing. See note on + * @description + * + * Represents the start of end of the Resolve phase of routing. See note on * {@link ChildActivationEnd} for use of this experimental API. * * @experimental @@ -320,7 +348,9 @@ export class ChildActivationStart { } /** - * @whatItDoes Represents the start of end of the Resolve phase of routing. See note on + * @description + * + * Represents the start of end of the Resolve phase of routing. See note on * {@link ChildActivationStart} for use of this experimental API. * * @experimental @@ -336,7 +366,9 @@ export class ChildActivationEnd { } /** - * @whatItDoes Represents the start of end of the Resolve phase of routing. See note on + * @description + * + * Represents the start of end of the Resolve phase of routing. See note on * {@link ActivationEnd} for use of this experimental API. * * @experimental @@ -352,7 +384,9 @@ export class ActivationStart { } /** - * @whatItDoes Represents the start of end of the Resolve phase of routing. See note on + * @description + * + * Represents the start of end of the Resolve phase of routing. See note on * {@link ActivationStart} for use of this experimental API. * * @experimental @@ -368,7 +402,9 @@ export class ActivationEnd { } /** - * @whatItDoes Represents a router event, allowing you to track the lifecycle of the router. + * @description + * + * Represents a router event, allowing you to track the lifecycle of the router. * * The sequence of router events is: * diff --git a/packages/router/src/interfaces.ts b/packages/router/src/interfaces.ts index 6864a6e224..cda64c574b 100644 --- a/packages/router/src/interfaces.ts +++ b/packages/router/src/interfaces.ts @@ -13,11 +13,10 @@ import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state'; /** - * @whatItDoes Interface that a class can implement to be a guard deciding if a route can be - * activated. - * * @description * + * Interface that a class can implement to be a guard deciding if a route can be activated. + * * ``` * class UserToken {} * class Permissions { @@ -84,11 +83,10 @@ export interface CanActivate { } /** - * @whatItDoes Interface that a class can implement to be a guard deciding if a child route can be - * activated. - * * @description * + * Interface that a class can implement to be a guard deciding if a child route can be activated. + * * ``` * class UserToken {} * class Permissions { @@ -165,11 +163,10 @@ export interface CanActivateChild { } /** - * @whatItDoes Interface that a class can implement to be a guard deciding if a route can be - * deactivated. - * * @description * + * Interface that a class can implement to be a guard deciding if a route can be deactivated. + * * ``` * class UserToken {} * class Permissions { @@ -240,10 +237,10 @@ export interface CanDeactivate { } /** - * @whatItDoes Interface that class can implement to be a data provider. - * * @description * + * Interface that class can implement to be a data provider. + * * ``` * class Backend { * fetchTeam(id: string) { @@ -312,11 +309,10 @@ export interface Resolve { /** - * @whatItDoes Interface that a class can implement to be a guard deciding if a children can be - * loaded. - * * @description * + * Interface that a class can implement to be a guard deciding if a children can be loaded. + * * ``` * class UserToken {} * class Permissions { diff --git a/packages/router/src/route_reuse_strategy.ts b/packages/router/src/route_reuse_strategy.ts index 6f142e045d..225acaa207 100644 --- a/packages/router/src/route_reuse_strategy.ts +++ b/packages/router/src/route_reuse_strategy.ts @@ -13,7 +13,9 @@ import {ActivatedRoute, ActivatedRouteSnapshot} from './router_state'; import {TreeNode} from './utils/tree'; /** - * @whatItDoes Represents the detached route tree. + * @description + * + * Represents the detached route tree. * * This is an opaque value the router will give to a custom route reuse strategy * to store and retrieve later on. @@ -30,7 +32,9 @@ export type DetachedRouteHandleInternal = { }; /** - * @whatItDoes Provides a way to customize when activated routes get reused. + * @description + * + * Provides a way to customize when activated routes get reused. * * @experimental */ diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts index 19066967c4..56ae3d4ce6 100644 --- a/packages/router/src/router.ts +++ b/packages/router/src/router.ts @@ -30,7 +30,9 @@ import {TreeNode, nodeChildrenAsMap} from './utils/tree'; /** - * @whatItDoes Represents the extra options used during navigation. + * @description + * + * Represents the extra options used during navigation. * * @stable */ @@ -142,9 +144,10 @@ export interface NavigationExtras { } /** - * @whatItDoes Error handler that is invoked when a navigation errors. - * * @description + * + * Error handler that is invoked when a navigation errors. + * * If the handler returns a value, the navigation promise will be resolved with this value. * If the handler throws an exception, the navigation promise will be rejected with * the exception. @@ -184,7 +187,9 @@ function defaultRouterHook(snapshot: RouterStateSnapshot): Observable { } /** - * @whatItDoes Provides the navigation and url manipulation capabilities. + * @description + * + * Provides the navigation and url manipulation capabilities. * * See {@link Routes} for more details and examples. * diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts index 126600a0f6..44d5baade2 100644 --- a/packages/router/src/router_module.ts +++ b/packages/router/src/router_module.ts @@ -29,13 +29,19 @@ import {flatten} from './utils/collection'; /** - * @whatItDoes Contains a list of directives + * @description + * + * Contains a list of directives + * * @stable */ const ROUTER_DIRECTIVES = [RouterOutlet, RouterLink, RouterLinkWithHref, RouterLinkActive]; /** - * @whatItDoes Is used in DI to configure the router. + * @description + * + * Is used in DI to configure the router. + * * @stable */ export const ROUTER_CONFIGURATION = new InjectionToken('ROUTER_CONFIGURATION'); @@ -71,8 +77,6 @@ export function routerNgProbeToken() { } /** - * @whatItDoes Adds router directives and providers. - * * @usageNotes * * RouterModule can be imported multiple times: once per lazily-loaded bundle. @@ -107,6 +111,8 @@ export function routerNgProbeToken() { * * @description * + * Adds router directives and providers. + * * Managing state transitions is one of the hardest parts of building applications. This is * especially true on the web, where you also need to ensure that the state is reflected in the URL. * In addition, we often want to split applications into multiple bundles and load them on demand. @@ -193,10 +199,10 @@ export function provideForRootGuard(router: Router): any { } /** - * @whatItDoes Registers routes. - * * @description * + * Registers routes. + * * ### Example * * ``` @@ -217,9 +223,10 @@ export function provideRoutes(routes: Routes): any { } /** - * @whatItDoes Represents an option to configure when the initial navigation is performed. - * * @description + * + * Represents an option to configure when the initial navigation is performed. + * * * 'enabled' - the initial navigation starts before the root component is created. * The bootstrap is blocked until the initial navigation is complete. * * 'disabled' - the initial navigation is not performed. The location listener is set up before @@ -244,7 +251,9 @@ export type InitialNavigation = true | false | 'enabled' | 'disabled' | 'legacy_enabled' | 'legacy_disabled'; /** - * @whatItDoes Represents options to configure the router. + * @description + * + * Represents options to configure the router. * * @stable */ diff --git a/packages/router/src/router_preloader.ts b/packages/router/src/router_preloader.ts index aceb6c3483..73ce802d29 100644 --- a/packages/router/src/router_preloader.ts +++ b/packages/router/src/router_preloader.ts @@ -17,7 +17,9 @@ import {RouterConfigLoader} from './router_config_loader'; /** - * @whatItDoes Provides a preloading strategy. + * @description + * + * Provides a preloading strategy. * * @experimental */ @@ -26,10 +28,10 @@ export abstract class PreloadingStrategy { } /** - * @whatItDoes Provides a preloading strategy that preloads all modules as quickly as possible. - * * @description * + * Provides a preloading strategy that preloads all modules as quickly as possible. + * * ``` * RouteModule.forRoot(ROUTES, {preloadingStrategy: PreloadAllModules}) * ``` @@ -43,10 +45,10 @@ export class PreloadAllModules implements PreloadingStrategy { } /** - * @whatItDoes Provides a preloading strategy that does not preload any modules. - * * @description * + * Provides a preloading strategy that does not preload any modules. + * * This strategy is enabled by default. * * @experimental diff --git a/packages/router/src/router_state.ts b/packages/router/src/router_state.ts index be191a3262..375d496d79 100644 --- a/packages/router/src/router_state.ts +++ b/packages/router/src/router_state.ts @@ -19,10 +19,10 @@ import {Tree, TreeNode} from './utils/tree'; /** - * @whatItDoes Represents the state of the router. - * * @description * + * Represents the state of the router. + * * 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. * @@ -85,12 +85,11 @@ export function createEmptyStateSnapshot( } /** - * @whatItDoes Contains the information about a route associated with a component loaded in an - * outlet. - * An `ActivatedRoute` can also be used to traverse the router state tree. - * * @description * + * Contains the information about a route associated with a component loaded in an + * outlet. An `ActivatedRoute` can also be used to traverse the router state tree. + * * ``` * @Component({...}) * class MyComponent { @@ -229,13 +228,12 @@ function flattenInherited(pathFromRoot: ActivatedRouteSnapshot[]): Inherited { } /** - * @whatItDoes Contains the information about a route associated with a component loaded in an - * outlet - * at a particular moment in time. ActivatedRouteSnapshot can also be used to traverse the router - * state tree. - * * @description * + * Contains the information about a route associated with a component loaded in an + * outlet at a particular moment in time. ActivatedRouteSnapshot can also be used to + * traverse the router state tree. + * * ``` * @Component({templateUrl:'./my-component.html'}) * class MyComponent { @@ -327,11 +325,11 @@ export class ActivatedRouteSnapshot { } /** - * @whatItDoes Represents the state of the router at a moment in time. - * * @description * - * RouterStateSnapshot is a tree of activated route snapshots. Every node in this tree knows about + * Represents the state of the router at a moment in time. + * + * This 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 diff --git a/packages/router/src/shared.ts b/packages/router/src/shared.ts index 341b216b23..b29c144007 100644 --- a/packages/router/src/shared.ts +++ b/packages/router/src/shared.ts @@ -11,7 +11,9 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree'; /** - * @whatItDoes Name of the primary outlet. + * @description + * + * Name of the primary outlet. * * @stable */ diff --git a/packages/router/src/url_handling_strategy.ts b/packages/router/src/url_handling_strategy.ts index 3d1dca723c..8394e68681 100644 --- a/packages/router/src/url_handling_strategy.ts +++ b/packages/router/src/url_handling_strategy.ts @@ -9,7 +9,9 @@ import {UrlTree} from './url_tree'; /** - * @whatItDoes Provides a way to migrate AngularJS applications to Angular. + * @description + * + * Provides a way to migrate AngularJS applications to Angular. * * @experimental */ diff --git a/packages/router/src/url_tree.ts b/packages/router/src/url_tree.ts index 8ff9345858..aac94dd96d 100644 --- a/packages/router/src/url_tree.ts +++ b/packages/router/src/url_tree.ts @@ -74,10 +74,10 @@ function containsSegmentGroupHelper( } /** - * @whatItDoes Represents the parsed URL. - * * @description * + * Represents the parsed URL. + * * 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 @@ -127,7 +127,9 @@ export class UrlTree { } /** - * @whatItDoes Represents the parsed URL segment group. + * @description + * + * Represents the parsed URL segment group. * * See {@link UrlTree} for more information. * @@ -161,10 +163,10 @@ export class UrlSegmentGroup { /** - * @whatItDoes Represents a single URL segment. - * * @description * + * Represents a single URL segment. + * * A UrlSegment is a part of a URL between the two slashes. It contains a path and the matrix * parameters associated with the segment. * @@ -234,9 +236,11 @@ export function mapChildrenIntoArray( /** - * @whatItDoes Serializes and deserializes a URL string into a URL tree. + * @description * - * @description The url serialization strategy is customizable. You can + * Serializes and deserializes a URL string into a URL tree. + * + * The url serialization strategy is customizable. You can * make all URLs case insensitive by providing a custom UrlSerializer. * * See {@link DefaultUrlSerializer} for an example of a URL serializer. @@ -252,10 +256,10 @@ export abstract class UrlSerializer { } /** - * @whatItDoes A default implementation of the {@link UrlSerializer}. - * * @description * + * A default implementation of the {@link UrlSerializer}. + * * Example URLs: * * ``` diff --git a/packages/router/testing/src/router_testing_module.ts b/packages/router/testing/src/router_testing_module.ts index 511405c9bd..2bc057ea66 100644 --- a/packages/router/testing/src/router_testing_module.ts +++ b/packages/router/testing/src/router_testing_module.ts @@ -14,10 +14,10 @@ import {ChildrenOutletContexts, ExtraOptions, NoPreloading, PreloadingStrategy, /** - * @whatItDoes Allows to simulate the loading of ng modules in tests. - * * @description * + * Allows to simulate the loading of ng modules in tests. + * * ``` * const loader = TestBed.get(NgModuleFactoryLoader); * @@ -131,10 +131,10 @@ export function setupTestingRouter( } /** - * @whatItDoes Sets up the router to be used for testing. - * * @description * + * Sets up the router to be used for testing. + * * The modules sets up the router to be used for testing. * It provides spy implementations of {@link Location}, {@link LocationStrategy}, and {@link * NgModuleFactoryLoader}. diff --git a/packages/router/upgrade/src/upgrade.ts b/packages/router/upgrade/src/upgrade.ts index 62570c1b61..184cf72b58 100644 --- a/packages/router/upgrade/src/upgrade.ts +++ b/packages/router/upgrade/src/upgrade.ts @@ -13,11 +13,11 @@ import {UpgradeModule} from '@angular/upgrade/static'; /** - * @whatItDoes Creates an initializer that in addition to setting up the Angular - * router sets up the ngRoute integration. - * * @description * + * Creates an initializer that in addition to setting up the Angular + * router sets up the ngRoute integration. + * * ``` * @NgModule({ * imports: [ @@ -50,7 +50,9 @@ export function locationSyncBootstrapListener(ngUpgrade: UpgradeModule) { } /** - * @whatItDoes Sets up a location synchronization. + * @description + * + * Sets up a location synchronization. * * History.pushState does not fire onPopState, so the Angular location * doesn't detect it. The workaround is to attach a location change listener