docs: update router api documentation (angular#37980)

Edit descriptions, usage examples, and add links to be complete and consistent with API reference doc style

PR Close angular#37980

Author: jbogarthyde

goldens/public-api/router/router.d.ts

@@ -148,7 +148,6 @@ export declare class GuardsCheckStart extends RouterEvent {
     toString(): string;
 }
 
-/** @deprecated */
 export declare type InitialNavigation = true | false | 'enabled' | 'disabled' | 'legacy_enabled' | 'legacy_disabled';
 
 export declare type LoadChildren = LoadChildrenCallback | DeprecatedLoadChildren;

packages/router/src/config.ts

@@ -22,6 +22,7 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
  *
  * @see `Route`
  * @see `Router`
+ * @see [Router configuration guide](guide/router#configuration)
  * @publicApi
  */
 export type Routes = Route[];
@@ -45,14 +46,12 @@ export type UrlMatchResult = {
  * for `Route.matcher` when a combination of `path` and `pathMatch`
  * is not expressive enough. Cannot be used together with `path` and `pathMatch`.
  *
- * @param segments An array of URL segments.
- * @param group A segment group.
- * @param route The route to match against.
- * @returns The match-result.
+ * The function takes the following arguments and returns a `UrlMatchResult` object.
+ * * *segments* : An array of URL segments.
+ * * *group* : A segment group.
+ * * *route* : The route to match against.
  *
- * @usageNotes
- *
- * The following matcher matches HTML files.
+ * The following example implementation matches HTML files.
  *
  * ```
  * export function htmlFiles(url: UrlSegment[]) {
@@ -94,8 +93,10 @@ export type ResolveData = {
 /**
  *
  * A function that is called to resolve a collection of lazy-loaded routes.
+ * Must be an arrow function of the following form:
+ * `() => import('...').then(mod => mod.MODULE)`
  *
- * Often this function will be implemented using an ES dynamic `import()` expression. For example:
+ * For example:
  *
  * ```
  * [{
@@ -104,35 +105,32 @@ export type ResolveData = {
  * }];
  * ```
  *
- * This function _must_ match the form above: an arrow function of the form
- * `() => import('...').then(mod => mod.MODULE)`.
- *
- * @see `Route#loadChildren`.
+ * @see [Route.loadChildren](api/router/Route#loadChildren)
  * @publicApi
  */
 export type LoadChildrenCallback = () => Type<any>|NgModuleFactory<any>|Observable<Type<any>>|
     Promise<NgModuleFactory<any>|Type<any>|any>;
 
 /**
  *
- * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load,
- * or a function that returns such a set.
+ * A function that returns a set of routes to load.
  *
  * The string form of `LoadChildren` is deprecated (see `DeprecatedLoadChildren`). The function
  * form (`LoadChildrenCallback`) should be used instead.
  *
- * @see `Route#loadChildren`.
+ * @see `loadChildrenCallback`
  * @publicApi
  */
 export type LoadChildren = LoadChildrenCallback|DeprecatedLoadChildren;
 
 /**
  * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load.
  *
- * @see `Route#loadChildren`
+ * @see `loadChildrenCallback`
  * @publicApi
- * @deprecated the `string` form of `loadChildren` is deprecated in favor of the proposed ES dynamic
- * `import()` expression, which offers a more natural and standards-based mechanism to dynamically
+ * @deprecated The `string` form of `loadChildren` is deprecated in favor of the
+ * `LoadChildrenCallback` function which uses the ES dynamic `import()` expression.
+ * This offers a more natural and standards-based mechanism to dynamically
  * load an ES module at runtime.
  */
 export type DeprecatedLoadChildren = string;
@@ -154,7 +152,7 @@ export type QueryParamsHandling = 'merge'|'preserve'|'';
  *
  * A policy for when to run guards and resolvers on a route.
  *
- * @see `Route#runGuardsAndResolvers`
+ * @see [Route.runGuardsAndResolvers](api/router/Route#runGuardsAndResolvers)
  * @publicApi
  */
 export type RunGuardsAndResolvers =
@@ -371,7 +369,8 @@ export type RunGuardsAndResolvers =
  *
  * Lazy loading speeds up application load time by splitting the application
  * into multiple bundles and loading them on demand.
- * To use lazy loading, provide the `loadChildren` property  instead of the `children` property.
+ * To use lazy loading, provide the `loadChildren` property in the `Route` object,
+ * instead of the `children` property.
  *
  * Given the following example route, the router will lazy load
  * the associated module on demand using the browser native import system.
@@ -470,7 +469,7 @@ export interface Route {
    */
   children?: Routes;
   /**
-   * A `LoadChildren` object specifying lazy-loaded child routes.
+   * An object specifying lazy-loaded child routes.
    */
   loadChildren?: LoadChildren;
   /**

packages/router/src/events.ts

@@ -24,7 +24,7 @@ export type NavigationTrigger = 'imperative'|'popstate'|'hashchange';
  * Base for events the router goes through, as opposed to events tied to a specific
  * route. Fired one time for any given navigation.
  *
- * @usageNotes
+ * The following code shows how a class subscribes to router events.
  *
  * ```ts
  * class MyService {
@@ -39,6 +39,7 @@ export type NavigationTrigger = 'imperative'|'popstate'|'hashchange';
  * ```
  *
  * @see `Event`
+ * @see [Router events summary](guide/router#router-events)
  * @publicApi
  */
 export class RouterEvent {
@@ -59,6 +60,9 @@ export class NavigationStart extends RouterEvent {
    * Identifies the call or event that triggered the navigation.
    * An `imperative` trigger is a call to `router.navigateByUrl()` or `router.navigate()`.
    *
+   * @see `NavigationEnd`
+   * @see `NavigationCancel`
+   * @see `NavigationError`
    */
   navigationTrigger?: 'imperative'|'popstate'|'hashchange';
 
@@ -104,6 +108,10 @@ export class NavigationStart extends RouterEvent {
 /**
  * An event triggered when a navigation ends successfully.
  *
+ * @see `NavigationStart`
+ * @see `NavigationCancel`
+ * @see `NavigationError`
+ *
  * @publicApi
  */
 export class NavigationEnd extends RouterEvent {
@@ -126,10 +134,13 @@ export class NavigationEnd extends RouterEvent {
 
 /**
  * An event triggered when a navigation is canceled, directly or indirectly.
- *
- * This can happen when a [route guard](guide/router-tutorial-toh#milestone-5-route-guards)
+ * This can happen when a route guard
  * returns `false` or initiates a redirect by returning a `UrlTree`.
  *
+ * @see `NavigationStart`
+ * @see `NavigationEnd`
+ * @see `NavigationError`
+ *
  * @publicApi
  */
 export class NavigationCancel extends RouterEvent {
@@ -152,6 +163,10 @@ export class NavigationCancel extends RouterEvent {
 /**
  * An event triggered when a navigation fails due to an unexpected error.
  *
+ * @see `NavigationStart`
+ * @see `NavigationEnd`
+ * @see `NavigationCancel`
+ *
  * @publicApi
  */
 export class NavigationError extends RouterEvent {
@@ -172,7 +187,7 @@ export class NavigationError extends RouterEvent {
 }
 
 /**
- *An event triggered when routes are recognized.
+ * An event triggered when routes are recognized.
  *
  * @publicApi
  */
@@ -199,6 +214,8 @@ export class RoutesRecognized extends RouterEvent {
 /**
  * An event triggered at the start of the Guard phase of routing.
  *
+ * @see `GuardsCheckEnd`
+ *
  * @publicApi
  */
 export class GuardsCheckStart extends RouterEvent {
@@ -223,6 +240,8 @@ export class GuardsCheckStart extends RouterEvent {
 /**
  * An event triggered at the end of the Guard phase of routing.
  *
+ * @see `GuardsCheckStart`
+ *
  * @publicApi
  */
 export class GuardsCheckEnd extends RouterEvent {
@@ -252,6 +271,8 @@ export class GuardsCheckEnd extends RouterEvent {
  * Runs in the "resolve" phase whether or not there is anything to resolve.
  * In future, may change to only run when there are things to be resolved.
  *
+ * @see `ResolveEnd`
+ *
  * @publicApi
  */
 export class ResolveStart extends RouterEvent {
@@ -301,6 +322,8 @@ export class ResolveEnd extends RouterEvent {
 /**
  * An event triggered before lazy loading a route configuration.
  *
+ * @see `RouteConfigLoadEnd`
+ *
  * @publicApi
  */
 export class RouteConfigLoadStart {
@@ -315,6 +338,8 @@ export class RouteConfigLoadStart {
 /**
  * An event triggered when a route has been lazy loaded.
  *
+ * @see `RouteConfigLoadStart`
+ *
  * @publicApi
  */
 export class RouteConfigLoadEnd {
@@ -348,7 +373,7 @@ export class ChildActivationStart {
  * An event triggered at the end of the child-activation part
  * of the Resolve phase of routing.
  * @see `ChildActivationStart`
- * @see `ResolveStart` *
+ * @see `ResolveStart`
  * @publicApi
  */
 export class ChildActivationEnd {
@@ -364,7 +389,7 @@ export class ChildActivationEnd {
 /**
  * An event triggered at the start of the activation part
  * of the Resolve phase of routing.
- * @see ActivationEnd`
+ * @see `ActivationEnd`
  * @see `ResolveStart`
  *
  * @publicApi
@@ -422,24 +447,33 @@ export class Scroll {
 /**
  * Router events that allow you to track the lifecycle of the router.
  *
- * The sequence of router events is as follows:
- *
- * - `NavigationStart`,
- * - `RouteConfigLoadStart`,
- * - `RouteConfigLoadEnd`,
- * - `RoutesRecognized`,
- * - `GuardsCheckStart`,
- * - `ChildActivationStart`,
- * - `ActivationStart`,
- * - `GuardsCheckEnd`,
- * - `ResolveStart`,
- * - `ResolveEnd`,
- * - `ActivationEnd`
- * - `ChildActivationEnd`
- * - `NavigationEnd`,
- * - `NavigationCancel`,
- * - `NavigationError`
- * - `Scroll`
+ * The events occur in the following sequence:
+ *
+ * * [NavigationStart](api/router/NavigationStart): Navigation starts.
+ * * [RouteConfigLoadStart](api/router/RouteConfigLoadStart): Before
+ * the router [lazy loads](/guide/router#lazy-loading) a route configuration.
+ * * [RouteConfigLoadEnd](api/router/RouteConfigLoadEnd): After a route has been lazy loaded.
+ * * [RoutesRecognized](api/router/RoutesRecognized): When the router parses the URL
+ * and the routes are recognized.
+ * * [GuardsCheckStart](api/router/GuardsCheckStart): When the router begins the *guards*
+ * phase of routing.
+ * * [ChildActivationStart](api/router/ChildActivationStart): When the router
+ * begins activating a route's children.
+ * * [ActivationStart](api/router/ActivationStart): When the router begins activating a route.
+ * * [GuardsCheckEnd](api/router/GuardsCheckEnd): When the router finishes the *guards*
+ * phase of routing successfully.
+ * * [ResolveStart](api/router/ResolveStart): When the router begins the *resolve*
+ * phase of routing.
+ * * [ResolveEnd](api/router/ResolveEnd): When the router finishes the *resolve*
+ * phase of routing successfuly.
+ * * [ChildActivationEnd](api/router/ChildActivationEnd): When the router finishes
+ * activating a route's children.
+ * * [ActivationEnd](api/router/ActivationStart): When the router finishes activating a route.
+ * * [NavigationEnd](api/router/NavigationEnd): When navigation ends successfully.
+ * * [NavigationCancel](api/router/NavigationCancel): When navigation is canceled.
+ * * [NavigationError](api/router/NavigationError): When navigation fails
+ * due to an unexpected error.
+ * * [Scroll](api/router/Scroll): When the user scrolls.
  *
  * @publicApi
  */