honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

The first line of the description is now used as an overview.

PR Close #23187
This commit is contained in:
Pete Bacon Darwin 2018-04-05 11:51:21 +01:00 committed by Igor Minar
parent f66f408b04
commit 31b90436b4
16 changed files with 184 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
packages/router/src/config.ts
View File

@ -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<any>| NgModuleFactory<any>| Promise<Type<any>>| Observable<Type<any>>;
/**
* @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
*/

8
packages/router/src/directives/router_link.ts
View File

@ -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.
*

5
packages/router/src/directives/router_link_active.ts
View File

@ -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:

5
packages/router/src/directives/router_outlet.ts
View File

@ -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.
*
* ```
* <router-outlet></router-outlet>
* <router-outlet name='left'></router-outlet>

72
packages/router/src/events.ts
View File

@ -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:
*

24
packages/router/src/interfaces.ts
View File

@ -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<T> {
}
/**
* @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<T> {
/**
* @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 {

8
packages/router/src/route_reuse_strategy.ts
View File

@ -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
*/

13
packages/router/src/router.ts
View File

@ -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<void> {
}
/**
* @whatItDoes Provides the navigation and url manipulation capabilities.
* @description
*
* Provides the navigation and url manipulation capabilities.
*
* See {@link Routes} for more details and examples.
*

27
packages/router/src/router_module.ts
View File

@ -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<ExtraOptions>('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
*/

12
packages/router/src/router_preloader.ts
View File

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

26
packages/router/src/router_state.ts
View File

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

4
packages/router/src/shared.ts
View File

@ -11,7 +11,9 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
/**
* @whatItDoes Name of the primary outlet.
* @description
*
* Name of the primary outlet.
*
* @stable
*/

4
packages/router/src/url_handling_strategy.ts
View File

@ -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
*/

22
packages/router/src/url_tree.ts
View File

@ -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<T>(
/**
* @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:
*
* ```

8
packages/router/testing/src/router_testing_module.ts
View File

@ -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}.

10
packages/router/upgrade/src/upgrade.ts
View File

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