diff --git a/packages/router/src/config.ts b/packages/router/src/config.ts
index 17e9ca699d..27acba6b19 100644
--- a/packages/router/src/config.ts
+++ b/packages/router/src/config.ts
@@ -93,16 +93,16 @@ export type ResolveData = {
 /**
  *
  * A function that is called to resolve a collection of lazy-loaded routes.
- * 
+ *
  * Often this function will be implemented using an ES dynamic `import()` expression. For example:
- * 
+ *
  * ```
  * [{
  *   path: 'lazy',
  *   loadChildren: () => import('./lazy-route/lazy.module').then(mod => mod.LazyModule),
  * }];
  * ```
- * 
+ *
  * This function _must_ match the form above: an arrow function of the form
  * `() => import('...').then(mod => mod.MODULE)`.
  *
@@ -143,7 +143,8 @@ export type DeprecatedLoadChildren = string;
  * - `merge` : Merge new with current parameters.
  * - `preserve` : Preserve current parameters.
  *
- * @see `RouterLink#queryParamsHandling`.
+ * @see `NavigationExtras#queryParamsHandling`
+ * @see `RouterLink`
  * @publicApi
  */
 export type QueryParamsHandling = 'merge' | 'preserve' | '';
diff --git a/packages/router/src/events.ts b/packages/router/src/events.ts
index 178594672b..edd4d12953 100644
--- a/packages/router/src/events.ts
+++ b/packages/router/src/events.ts
@@ -10,27 +10,23 @@ import {Route} from './config';
 import {ActivatedRouteSnapshot, RouterStateSnapshot} from './router_state';
 
 /**
- * @description
+ * Identifies the call or event that triggered a navigation.
  *
- * Identifies the trigger of the navigation.
- *
- * * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`.
- * * 'popstate'--triggered by a popstate event
- * * 'hashchange'--triggered by a hashchange event
+ * * 'imperative': Triggered by `router.navigateByUrl()` or `router.navigate()`.
+ * * 'popstate' : Triggered by a `popstate` event.
+ * * 'hashchange'-: Triggered by a `hashchange` event.
  *
  * @publicApi
  */
 export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange';
 
 /**
- * @description
+ * Base for events the router goes through, as opposed to events tied to a specific
+ * route. Fired one time for any given navigation.
  *
- * 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.
+ * @usageNotes
  *
- * Example:
- *
- * ```
+ * ```ts
  * class MyService {
  *   constructor(public router: Router, logger: Logger) {
  *     router.events.pipe(
@@ -42,46 +38,46 @@ export type NavigationTrigger = 'imperative' | 'popstate' | 'hashchange';
  * }
  * ```
  *
+ * @see `Event`
  * @publicApi
  */
 export class RouterEvent {
   constructor(
-      /** @docsNotRequired */
+      /** A unique ID that the router assigns to every router navigation. */
       public id: number,
-      /** @docsNotRequired */
+      /** The URL that is the destination for this navigation. */
       public url: string) {}
 }
 
 /**
- * @description
- *
- * Represents an event triggered when a navigation starts.
+ * An event triggered when a navigation starts.
  *
  * @publicApi
  */
 export class NavigationStart extends RouterEvent {
   /**
-   * Identifies the trigger of the navigation.
+   * Identifies the call or event that triggered the navigation.
+   * An `imperative` trigger is a call to `router.navigateByUrl()` or `router.navigate()`.
    *
-   * * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`.
-   * * 'popstate'--triggered by a popstate event
-   * * 'hashchange'--triggered by a hashchange event
    */
   navigationTrigger?: 'imperative'|'popstate'|'hashchange';
 
   /**
-   * This reflects the state object that was previously supplied to the pushState call. This is
-   * not null only when the navigation is triggered by a popstate event.
+   * The navigation state that was previously supplied to the `pushState` call,
+   * when the navigation is triggered by a `popstate` event. Otherwise null.
    *
-   * The router assigns a navigationId to every router transition/navigation. Even when the user
-   * clicks on the back button in the browser, a new navigation id will be created. So from
-   * the perspective of the router, the router never "goes back". By using the `restoredState`
-   * and its navigationId, you can implement behavior that differentiates between creating new
-   * states
-   * and popstate events. In the latter case you can restore some remembered state (e.g., scroll
-   * position).
+   * The state object is defined by `NavigationExtras`, and contains any
+   * developer-defined state value, as well as a unique ID that
+   * the router assigns to every router transition/navigation.
+   *
+   * From the perspective of the router, the router never "goes back".
+   * When the user clicks on the back button in the browser,
+   * a new navigation ID is created.
+   *
+   * Use the ID in this previous-state object to differentiate between a newly created
+   * state and one returned to by a `popstate` event, so that you can restore some
+   * remembered state, such as scroll position.
    *
-   * See {@link NavigationExtras} for more information.
    */
   restoredState?: {[k: string]: any, navigationId: number}|null;
 
@@ -104,9 +100,7 @@ export class NavigationStart extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents an event triggered when a navigation ends successfully.
+ * An event triggered when a navigation ends successfully.
  *
  * @publicApi
  */
@@ -128,9 +122,7 @@ export class NavigationEnd extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents an event triggered when a navigation is canceled.
+ * An event triggered when a navigation is canceled.
  *
  * @publicApi
  */
@@ -150,9 +142,7 @@ export class NavigationCancel extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents an event triggered when a navigation fails due to an unexpected error.
+ * An event triggered when a navigation fails due to an unexpected error.
  *
  * @publicApi
  */
@@ -174,9 +164,7 @@ export class NavigationError extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents an event triggered when routes are recognized.
+ *An event triggered when routes are recognized.
  *
  * @publicApi
  */
@@ -200,9 +188,7 @@ export class RoutesRecognized extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents the start of the Guard phase of routing.
+ * An event triggered at the start of the Guard phase of routing.
  *
  * @publicApi
  */
@@ -225,9 +211,7 @@ export class GuardsCheckStart extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents the end of the Guard phase of routing.
+ * An event triggered at the end of the Guard phase of routing.
  *
  * @publicApi
  */
@@ -252,12 +236,10 @@ export class GuardsCheckEnd extends RouterEvent {
 }
 
 /**
- * @description
+ * An event triggered at the the start of the Resolve phase of routing.
  *
- * 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.
+ * 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.
  *
  * @publicApi
  */
@@ -280,10 +262,8 @@ export class ResolveStart extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents the end of the Resolve phase of routing. See note on
- * `ResolveStart` for use of this experimental API.
+ * An event triggered at the end of the Resolve phase of routing.
+ * @see `ResolveStart`.
  *
  * @publicApi
  */
@@ -306,9 +286,7 @@ export class ResolveEnd extends RouterEvent {
 }
 
 /**
- * @description
- *
- * Represents an event triggered before lazy loading a route config.
+ * An event triggered before lazy loading a route configuration.
  *
  * @publicApi
  */
@@ -320,9 +298,7 @@ export class RouteConfigLoadStart {
 }
 
 /**
- * @description
- *
- * Represents an event triggered when a route has been lazy loaded.
+ * An event triggered when a route has been lazy loaded.
  *
  * @publicApi
  */
@@ -334,10 +310,10 @@ export class RouteConfigLoadEnd {
 }
 
 /**
- * @description
- *
- * Represents the start of end of the Resolve phase of routing. See note on
- * `ChildActivationEnd` for use of this experimental API.
+ * An event triggered at the start of the child-activation
+ * part of the Resolve phase of routing.
+ * @see  `ChildActivationEnd`
+ * @see `ResolveStart`
  *
  * @publicApi
  */
@@ -352,11 +328,10 @@ export class ChildActivationStart {
 }
 
 /**
- * @description
- *
- * Represents the start of end of the Resolve phase of routing. See note on
- * `ChildActivationStart` for use of this experimental API.
- *
+ * An event triggered at the end of the child-activation part
+ * of the Resolve phase of routing.
+ * @see `ChildActivationStart`
+ * @see `ResolveStart` *
  * @publicApi
  */
 export class ChildActivationEnd {
@@ -370,10 +345,10 @@ export class ChildActivationEnd {
 }
 
 /**
- * @description
- *
- * Represents the start of end of the Resolve phase of routing. See note on
- * `ActivationEnd` for use of this experimental API.
+ * An event triggered at the start of the activation part
+ * of the Resolve phase of routing.
+ * @see ActivationEnd`
+ * @see `ResolveStart`
  *
  * @publicApi
  */
@@ -388,10 +363,10 @@ export class ActivationStart {
 }
 
 /**
- * @description
- *
- * Represents the start of end of the Resolve phase of routing. See note on
- * `ActivationStart` for use of this experimental API.
+ * An event triggered at the end of the activation part
+ * of the Resolve phase of routing.
+ * @see `ActivationStart`
+ * @see `ResolveStart`
  *
  * @publicApi
  */
@@ -406,9 +381,7 @@ export class ActivationEnd {
 }
 
 /**
- * @description
- *
- * Represents a scrolling event.
+ * An event triggered by scrolling.
  *
  * @publicApi
  */
@@ -430,11 +403,9 @@ export class Scroll {
 }
 
 /**
- * @description
+ * Router events that allow you to track the lifecycle of the router.
  *
- * Represents a router event, allowing you to track the lifecycle of the router.
- *
- * The sequence of router events is:
+ * The sequence of router events is as follows:
  *
  * - `NavigationStart`,
  * - `RouteConfigLoadStart`,
diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts
index 4362289a19..f865efc88d 100644
--- a/packages/router/src/index.ts
+++ b/packages/router/src/index.ts
@@ -7,7 +7,7 @@
  */
 
 
-export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config';
+export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, QueryParamsHandling, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config';
 export {RouterLink, RouterLinkWithHref} from './directives/router_link';
 export {RouterLinkActive} from './directives/router_link_active';
 export {RouterOutlet} from './directives/router_outlet';
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
index c19621c0c8..6bfe688915 100644
--- a/packages/router/src/router.ts
+++ b/packages/router/src/router.ts
@@ -42,9 +42,10 @@ import {isUrlTree} from './utils/type_guards';
  */
 export interface NavigationExtras {
   /**
-   * Enables relative navigation from the current ActivatedRoute.
+   * Specifies a root URI to use for relative navigation.
    *
-   * Configuration:
+   * For example, consider the following route configuration where the parent route
+   * has two children.
    *
    * ```
    * [{
@@ -60,7 +61,8 @@ export interface NavigationExtras {
   * }]
    * ```
    *
-   * Navigate to list route from child route:
+   * The following `go()` function navigates to the `list` route by
+   * interpreting the destination URI as relative to the activated `child`  route
    *
    * ```
    *  @Component({...})
@@ -96,20 +98,18 @@ export interface NavigationExtras {
   fragment?: string;
 
   /**
-   * DEPRECATED: Use `queryParamsHandling` instead to preserve
+   * **DEPRECATED**: Use `queryParamsHandling: "preserve"` instead to preserve
    * query parameters for the next navigation.
    *
-   * ```
-   * // Preserve query params from /results?page=1 to /view?page=1
-   * this.router.navigate(['/view'], { preserveQueryParams: true });
-   * ```
-   *
    * @deprecated since v4
    */
   preserveQueryParams?: boolean;
 
   /**
-   * Configuration strategy for how to handle query parameters for the next navigation.
+   * How to handle query parameters in the router link for the next navigation.
+   * One of:
+   * * `merge` : Merge new with current parameters.
+   * * `preserve` : Preserve current parameters.
    *
    * ```
    * // from /results?page=1 to /view?page=1&page=2
@@ -118,7 +118,7 @@ export interface NavigationExtras {
    */
   queryParamsHandling?: QueryParamsHandling|null;
   /**
-   * Preserves the fragment for the next navigation
+   * When true, preserves the URL fragment for the next navigation
    *
    * ```
    * // Preserve fragment from /results#top to /view#top
@@ -127,7 +127,7 @@ export interface NavigationExtras {
    */
   preserveFragment?: boolean;
   /**
-   * Navigates without pushing a new state into history.
+   * When true, navigates without pushing a new state into history.
    *
    * ```
    * // Navigate silently to /view
@@ -136,7 +136,7 @@ export interface NavigationExtras {
    */
   skipLocationChange?: boolean;
   /**
-   * Navigates while replacing the current state in history.
+   * When true, navigates while replacing the current state in history.
    *
    * ```
    * // Navigate to /view
@@ -145,26 +145,26 @@ export interface NavigationExtras {
    */
   replaceUrl?: boolean;
   /**
-   * State passed to any navigation. This value will be accessible through the `extras` object
-   * returned from `router.getCurrentNavigation()` while a navigation is executing. Once a
-   * navigation completes, this value will be written to `history.state` when the `location.go`
-   * or `location.replaceState` method is called before activating of this route. Note that
-   * `history.state` will not pass an object equality test because the `navigationId` will be
-   * added to the state before being written.
+   * Developer-defined state that can be passed to any navigation.
+   * Access this value through the `Navigation.extras` object
+   * returned from `router.getCurrentNavigation()` while a navigation is executing.
    *
-   * While `history.state` can accept any type of value, because the router adds the `navigationId`
-   * on each navigation, the `state` must always be an object.
+   * After a navigation completes, the router writes an object containing this
+   * value together with a `navigationId` to `history.state`.
+   * The value is written when `location.go()` or `location.replaceState()`
+   * is called before activating this route.
+   *
+   * Note that `history.state` does not pass an object equality test because
+   * the router adds the `navigationId` on each navigation.
    */
   state?: {[k: string]: any};
 }
 
 /**
- * @description
+ * Error handler that is invoked when a navigation error occurs.
  *
- * 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
+ * If the handler returns a value, the navigation promise is resolved with this value.
+ * If the handler throws an exception, the navigation promise is rejected with
  * the exception.
  *
  * @publicApi
@@ -185,10 +185,8 @@ export type RestoredState = {
 };
 
 /**
- * @description
- *
- * Information about any given navigation. This information can be gotten from the router at
- * any time using the `router.getCurrentNavigation()` method.
+ * Information about a navigation operation. Retrieve the most recent
+ * navigation object with the `router.getCurrentNavigation()` method.
  *
  * @publicApi
  */
@@ -198,35 +196,37 @@ export type Navigation = {
    */
   id: number;
   /**
-   * Target URL passed into the {@link Router#navigateByUrl} call before navigation. This is
+   * The target URL passed into the `Router#navigateByUrl()` call before navigation. This is
    * the value before the router has parsed or applied redirects to it.
    */
   initialUrl: string | UrlTree;
   /**
-   * The initial target URL after being parsed with {@link UrlSerializer.extract()}.
+   * The initial target URL after being parsed with `UrlSerializer.extract()`.
    */
   extractedUrl: UrlTree;
   /**
-   * Extracted URL after redirects have been applied. This URL may not be available immediately,
-   * therefore this property can be `undefined`. It is guaranteed to be set after the
-   * {@link RoutesRecognized} event fires.
+   * The extracted URL after redirects have been applied.
+   * This URL may not be available immediately, therefore this property can be `undefined`.
+   * It is guaranteed to be set after the `RoutesRecognized` event fires.
    */
   finalUrl?: UrlTree;
   /**
-   * Identifies the trigger of the navigation.
+   * Identifies how this navigation was triggered.
    *
-   * * 'imperative'--triggered by `router.navigateByUrl` or `router.navigate`.
-   * * 'popstate'--triggered by a popstate event
-   * * 'hashchange'--triggered by a hashchange event
+   * * 'imperative'--Triggered by `router.navigateByUrl` or `router.navigate`.
+   * * 'popstate'--Triggered by a popstate event.
+   * * 'hashchange'--Triggered by a hashchange event.
    */
   trigger: 'imperative' | 'popstate' | 'hashchange';
   /**
-   * The NavigationExtras used in this navigation. See {@link NavigationExtras} for more info.
+   * Options that controlled the strategy used for this navigation.
+   * See `NavigationExtras`.
    */
   extras: NavigationExtras;
   /**
-   * Previously successful Navigation object. Only a single previous Navigation is available,
-   * therefore this previous Navigation will always have a `null` value for `previousNavigation`.
+   * The previously successful `Navigation` object. Only one previous navigation
+   * is available, therefore this previous `Navigation` object has a `null` value
+   * for its own `previousNavigation`.
    */
   previousNavigation: Navigation | null;
 };
@@ -320,8 +320,9 @@ export class Router {
   errorHandler: ErrorHandler = defaultErrorHandler;
 
   /**
-   * Malformed uri error handler is invoked when `Router.parseUrl(url)` throws an
-   * error due to containing an invalid character. The most common case would be a `%` sign
+   * A handler for errors thrown by `Router.parseUrl(url)`
+   * when `url` contains an invalid character.
+   * The most common case is a `%` sign
    * that's not encoded and is not part of a percent encoded sequence.
    */
   malformedUriErrorHandler:
@@ -348,12 +349,13 @@ export class Router {
   };
 
   /**
-   * Extracts and merges URLs. Used for AngularJS to Angular migrations.
+   * A strategy for extracting and merging URLs.
+   * Used for AngularJS to Angular migrations.
    */
   urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy();
 
   /**
-   * The strategy for re-using routes.
+   * A strategy for re-using routes.
    */
   routeReuseStrategy: RouteReuseStrategy = new DefaultRouteReuseStrategy();
 
@@ -376,19 +378,17 @@ export class Router {
   paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
 
   /**
-   * Defines when the router updates the browser URL. The default behavior is to update after
-   * successful navigation. However, some applications may prefer a mode where the URL gets
-   * updated at the beginning of navigation. The most common use case would be updating the
-   * URL early so if navigation fails, you can show an error message with the URL that failed.
-   * Available options are:
-   *
-   * - `'deferred'`, the default, updates the browser URL after navigation has finished.
-   * - `'eager'`, updates browser URL at the beginning of navigation.
+   * Determines when the router updates the browser URL.
+   * By default (`"deferred"`), udates the browser URL after navigation has finished.
+   * Set to `'eager'` to update the browser URL at the beginning of navigation.
+   * You can choose to update early so that, if navigation fails,
+   * you can show an error message with the URL that failed.
    */
   urlUpdateStrategy: 'deferred'|'eager' = 'deferred';
 
   /**
-   * See {@link RouterModule} for more information.
+   * Enables a bug fix that corrects relative link resolution in components with empty paths.
+   * @see `RouterModule`
    */
   relativeLinkResolution: 'legacy'|'corrected' = 'legacy';
 
@@ -864,10 +864,10 @@ export class Router {
    * Applies an array of commands to the current URL tree and creates a new URL tree.
    *
    * When given an activate route, applies the given commands starting from the route.
-   * When not given a route, applies the given command starting from the root.
+   * Otherwise, applies the given command starting from the root.
    *
    * @param commands An array of commands to apply.
-   * @param navigationExtras
+   * @param navigationExtras Options that control the navigation strategy.
    * @returns The new URL tree.
    *
    * @usageNotes
@@ -882,9 +882,8 @@ export class Router {
    * // you can collapse static segments like this (this works only with the first passed-in value):
    * router.createUrlTree(['/team/33/user', userId]);
    *
-   * // If the first segment can contain slashes, and you do not want the router to split it, you
-   * // can do the following:
-   *
+   * // If the first segment can contain slashes, and you do not want the router to split it,
+   * // you can do the following:
    * router.createUrlTree([{segmentPath: '/one/two'}]);
    *
    * // create /team/33/(user/11//right:chat)
@@ -947,8 +946,6 @@ export class Router {
    *
    * @usageNotes
    *
-   * ### Example
-   *
    * ```
    * router.navigateByUrl("/team/33/user/11");
    *
@@ -981,8 +978,6 @@ export class Router {
    *
    * @usageNotes
    *
-   * ### Example
-   *
    * ```
    * router.navigate(['team', 33, 'user', 11], {relativeTo: route});
    *
diff --git a/packages/router/src/router_config_loader.ts b/packages/router/src/router_config_loader.ts
index 6f5d981cf7..a3a12ed8c0 100644
--- a/packages/router/src/router_config_loader.ts
+++ b/packages/router/src/router_config_loader.ts
@@ -13,7 +13,8 @@ import {LoadChildren, LoadedRouterConfig, Route, standardizeConfig} from './conf
 import {flatten, wrapIntoObservable} from './utils/collection';
 
 /**
- * @docsNotRequired
+ * The [DI token](guide/glossary/#di-token) for a router configuration.
+ * @see `ROUTES`
  * @publicApi
  */
 export const ROUTES = new InjectionToken<Route[][]>('ROUTES');
diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts
index 27c607fc0e..27f768b4ec 100644
--- a/packages/router/src/router_module.ts
+++ b/packages/router/src/router_module.ts
@@ -31,19 +31,13 @@ import {flatten} from './utils/collection';
 
 
 /**
- * @description
- *
- * Contains a list of directives
- *
- *
+ * The directives defined in the `RouterModule`.
  */
 const ROUTER_DIRECTIVES =
     [RouterOutlet, RouterLink, RouterLinkWithHref, RouterLinkActive, EmptyOutletComponent];
 
 /**
- * @description
- *
- * Is used in DI to configure the router.
+ * A [DI token](guide/glossary/#di-token) for the router service.
  *
  * @publicApi
  */
@@ -121,12 +115,12 @@ export function routerNgProbeToken() {
  * In addition, we often want to split applications into multiple bundles and load them on demand.
  * Doing this transparently is not trivial.
  *
- * The Angular router solves these problems. Using the router, you can declaratively specify
+ * The Angular router service solves these problems. Using the router, you can declaratively specify
  * application states, manage state transitions while taking care of the URL, and load bundles on
  * demand.
  *
- * [Read this developer guide](https://angular.io/docs/ts/latest/guide/router.html) to get an
- * overview of how the router should be used.
+ * @see [Routing and Navigation](guide/router.html) for an
+ * overview of how the router service should be used.
  *
  * @publicApi
  */
@@ -140,34 +134,12 @@ export class RouterModule {
   constructor(@Optional() @Inject(ROUTER_FORROOT_GUARD) guard: any, @Optional() router: Router) {}
 
   /**
-   * Creates a module with all the router providers and directives. It also optionally sets up an
-   * application listener to perform an initial navigation.
+   * Creates and configures a module with all the router providers and directives.
+   * Optionally sets up an application listener to perform an initial navigation.
    *
-   * Configuration Options:
-   *
-   * * `enableTracing` Toggles whether the router should log all navigation events to the console.
-   * * `useHash` Enables the location strategy that uses the URL fragment instead of the history
-   * API.
-   * * `initialNavigation` Disables the initial navigation.
-   * * `errorHandler` Defines a custom error handler for failed navigations.
-   * * `preloadingStrategy` Configures a preloading strategy. See `PreloadAllModules`.
-   * * `onSameUrlNavigation` Define what the router should do if it receives a navigation request to
-   * the current URL.
-   * * `scrollPositionRestoration` Configures if the scroll position needs to be restored when
-   * navigating back.
-   * * `anchorScrolling` Configures if the router should scroll to the element when the url has a
-   * fragment.
-   * * `scrollOffset` Configures the scroll offset the router will use when scrolling to an element.
-   * * `paramsInheritanceStrategy` Defines how the router merges params, data and resolved data from
-   * parent to child routes.
-   * * `malformedUriErrorHandler` Defines a custom malformed uri error handler function. This
-   * handler is invoked when encodedURI contains invalid character sequences.
-   * * `urlUpdateStrategy` Defines when the router updates the browser URL. The default behavior is
-   * to update after successful navigation.
-   * * `relativeLinkResolution` Enables the correct relative link resolution in components with
-   * empty paths.
-   *
-   * See `ExtraOptions` for more details about the above options.
+   * @param routes An array of `Route` objects that define the navigation paths for the application.
+   * @param config An `ExtraOptions` configuration object that controls how navigation is performed.
+   * @return The new router module.
   */
   static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders<RouterModule> {
     return {
@@ -235,12 +207,10 @@ export function provideForRootGuard(router: Router): any {
 }
 
 /**
- * @description
- *
- * Registers routes.
+ * Registers a [DI provider](guide/glossary#provider) for a set of routes.
+ * @param routes The route configuration to provide.
  *
  * @usageNotes
- * ### Example
  *
  * ```
  * @NgModule({
@@ -260,70 +230,75 @@ export function provideRoutes(routes: Routes): any {
 }
 
 /**
- * @description
+ * Allowed values in an `ExtraOptions` object that configure
+ * when the router performs the initial navigation operation.
  *
- * Represents an option to configure when the initial navigation is performed.
- *
- * * 'enabled' - the initial navigation starts before the root component is created.
+ * * 'enabled' (Default) 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
- * the root component gets created.
- * * 'legacy_enabled'- the initial navigation starts after the root component has been created.
+ * * 'disabled' - The initial navigation is not performed. The location listener is set up before
+ * the root component gets created. Use if there is a reason to have
+ * more control over when the router starts its initial navigation due to some complex
+ * initialization logic.
+ * * 'legacy_enabled'- The initial navigation starts after the root component has been created.
  * The bootstrap is not blocked until the initial navigation is complete. @deprecated
- * * 'legacy_disabled'- the initial navigation is not performed. The location listener is set up
- * after @deprecated
- * the root component gets created.
+ * * 'legacy_disabled'- The initial navigation is not performed. The location listener is set up
+ * after the root component gets created. @deprecated
  * * `true` - same as 'legacy_enabled'. @deprecated since v4
  * * `false` - same as 'legacy_disabled'. @deprecated since v4
  *
- * The 'enabled' option should be used for applications unless there is a reason to have
- * more control over when the router starts its initial navigation due to some complex
- * initialization logic. In this case, 'disabled' should be used.
- *
  * The 'legacy_enabled' and 'legacy_disabled' should not be used for new applications.
  *
+ * @see `forRoot()`
+ *
  * @publicApi
  */
 export type InitialNavigation =
     true | false | 'enabled' | 'disabled' | 'legacy_enabled' | 'legacy_disabled';
 
 /**
- * @description
- *
- * Represents options to configure the router.
+ * A set of configuration options for a router module, provided in the
+ * `forRoot()` method.
  *
  * @publicApi
  */
 export interface ExtraOptions {
   /**
-   * Makes the router log all its internal events to the console.
+   * When true, log all internal navigation events to the console.
+   * Use for debugging.
    */
   enableTracing?: boolean;
 
   /**
-   * Enables the location strategy that uses the URL fragment instead of the history API.
+   * When true, enable the location strategy that uses the URL fragment
+   * instead of the history API.
    */
   useHash?: boolean;
 
   /**
-   * Disables the initial navigation.
+   * One of `enabled` (the default) or `disabled`.
+   * By default, the initial navigation starts before the root component is created.
+   * The bootstrap is blocked until the initial navigation is complete.
+   * When set to `disabled`, the initial navigation is not performed.
+   * The location listener is set up before the root component gets created.
    */
   initialNavigation?: InitialNavigation;
 
   /**
-   * A custom error handler.
+   * A custom error handler for failed navigations.
    */
   errorHandler?: ErrorHandler;
 
   /**
-   * Configures a preloading strategy. See `PreloadAllModules`.
+   * Configures a preloading strategy.
+   * One of `PreloadAllModules` or `NoPreloading` (the default).
    */
   preloadingStrategy?: any;
 
   /**
    * Define what the router should do if it receives a navigation request to the current URL.
-   * By default, the router will ignore this navigation. However, this prevents features such
-   * as a "refresh" button. Use this option to configure the behavior when navigating to the
+   * Default is `ignore`, which causes the router ignores the navigation.
+   * This can disable features such as a "refresh" button.
+   * Use this option to configure the behavior when navigating to the
    * current URL. Default is 'ignore'.
    */
   onSameUrlNavigation?: 'reload'|'ignore';
@@ -331,14 +306,15 @@ export interface ExtraOptions {
   /**
    * Configures if the scroll position needs to be restored when navigating back.
    *
-   * * 'disabled'--does nothing (default).  Scroll position will be maintained on navigation.
-   * * 'top'--set the scroll position to x = 0, y = 0 on all navigation.
-   * * 'enabled'--restores the previous scroll position on backward navigation, else sets the
+   * * 'disabled'- (Default) Does nothing. Scroll position is maintained on navigation.
+   * * 'top'- Sets the scroll position to x = 0, y = 0 on all navigation.
+   * * 'enabled'- Restores the previous scroll position on backward navigation, else sets the
    * position to the anchor if one is provided, or sets the scroll position to [0, 0] (forward
    * navigation). This option will be the default in the future.
    *
    * You can implement custom scroll restoration behavior by adapting the enabled behavior as
-   * follows:
+   * in the following example.
+   *
    * ```typescript
    * class AppModule {
     *   constructor(router: Router, viewportScroller: ViewportScroller) {
@@ -363,10 +339,8 @@ export interface ExtraOptions {
   scrollPositionRestoration?: 'disabled'|'enabled'|'top';
 
   /**
-   * Configures if the router should scroll to the element when the url has a fragment.
-   *
-   * * 'disabled'--does nothing (default).
-   * * 'enabled'--scrolls to the element. This option will be the default in the future.
+   * When set to 'enabled', scrolls to the anchor element when the URL has a fragment.
+   * Anchor scrolling is disabled by default.
    *
    * Anchor scrolling does not happen on 'popstate'. Instead, we restore the position
    * that we stored or scroll to the top.
@@ -376,28 +350,28 @@ export interface ExtraOptions {
   /**
    * Configures the scroll offset the router will use when scrolling to an element.
    *
-   * When given a tuple with two numbers, the router will always use the numbers.
-   * When given a function, the router will invoke the function every time it restores scroll
-   * position.
+   * When given a tuple with x and y position value,
+   * the router uses that offset each time it scrolls.
+   * When given a function, the router invokes the function every time
+   * it restores scroll position.
    */
   scrollOffset?: [number, number]|(() => [number, number]);
 
   /**
-   * Defines how the router merges params, data and resolved data from parent to child
-   * routes. Available options are:
-   *
-   * - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less
-   *   routes.
-   * - `'always'`, enables unconditional inheritance of parent params.
+   * Defines how the router merges parameters, data, and resolved data from parent to child
+   * routes. By default ('emptyOnly'), inherits parent parameters only for
+   * path-less or component-less routes.
+   * Set to 'always' to enable unconditional inheritance of parent parameters.
    */
   paramsInheritanceStrategy?: 'emptyOnly'|'always';
 
   /**
-   * A custom malformed uri error handler function. This handler is invoked when encodedURI contains
-   * invalid character sequences. The default implementation is to redirect to the root url dropping
-   * any path or param info. This function passes three parameters:
+   * A custom handler for malformed URI errors. The handler is invoked when `encodedURI` contains
+   * invalid character sequences.
+   * The default implementation is to redirect to the root URL, dropping
+   * any path or parameter information. The function takes three parameters:
    *
-   * - `'URIError'` - Error thrown when parsing a bad URL
+   * - `'URIError'` - Error thrown when parsing a bad URL.
    * - `'UrlSerializer'` - UrlSerializer that’s configured with the router.
    * - `'url'` -  The malformed URL that caused the URIError
    * */
@@ -405,14 +379,11 @@ export interface ExtraOptions {
       (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
 
   /**
-   * Defines when the router updates the browser URL. The default behavior is to update after
-   * successful navigation. However, some applications may prefer a mode where the URL gets
-   * updated at the beginning of navigation. The most common use case would be updating the
-   * URL early so if navigation fails, you can show an error message with the URL that failed.
-   * Available options are:
-   *
-   * - `'deferred'`, the default, updates the browser URL after navigation has finished.
-   * - `'eager'`, updates browser URL at the beginning of navigation.
+   * Defines when the router updates the browser URL. By default ('deferred'),
+   * update after successful navigation.
+   * Set to 'eager' if prefer to update the URL at the beginning of navigation.
+   * Updating the URL early allows you to handle a failure of navigation by
+   * showing an error message with the URL that failed.
    */
   urlUpdateStrategy?: 'deferred'|'eager';
 
@@ -505,13 +476,13 @@ export function rootRoute(router: Router): ActivatedRoute {
 }
 
 /**
- * To initialize the router properly we need to do in two steps:
+ * Router initialization requires two steps:
  *
- * We need to start the navigation in a APP_INITIALIZER to block the bootstrap if
- * a resolver or a guards executes asynchronously. Second, we need to actually run
- * activation in a BOOTSTRAP_LISTENER. We utilize the afterPreactivation
- * hook provided by the router to do that.
+ * First, we start the navigation in a `APP_INITIALIZER` to block the bootstrap if
+ * a resolver or a guard executes asynchronously.
  *
+ * Next, we actually run activation in a `BOOTSTRAP_LISTENER`, using the
+ * `afterPreactivation` hook provided by the router.
  * The router navigation starts, reaches the point when preactivation is done, and then
  * pauses. It waits for the hook to be resolved. We then resolve it only in a bootstrap listener.
  */
@@ -603,7 +574,8 @@ export function getBootstrapListener(r: RouterInitializer) {
 }
 
 /**
- * A token for the router initializer that will be called after the app is bootstrapped.
+ * A [DI token](guide/glossary/#di-token) for the router initializer that
+ * is called after the app is bootstrapped.
  *
  * @publicApi
  */
diff --git a/packages/router/src/router_state.ts b/packages/router/src/router_state.ts
index 10ee3e35f3..8936bfc20f 100644
--- a/packages/router/src/router_state.ts
+++ b/packages/router/src/router_state.ts
@@ -19,14 +19,15 @@ import {Tree, TreeNode} from './utils/tree';
 
 
 /**
- * @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.
+ * Represents the state of the router as a tree of activated routes.
  *
  * @usageNotes
+ *
+ * Every node in the route tree is an `ActivatedRoute` instance
+ * that knows about the "consumed" URL segments, the extracted parameters,
+ * and the resolved data.
+ * Use the `ActivatedRoute` properties to traverse the tree from any node.
+ *
  * ### Example
  *
  * ```
@@ -42,7 +43,7 @@ import {Tree, TreeNode} from './utils/tree';
  * }
  * ```
  *
- * See `ActivatedRoute` for more information.
+ * @see `ActivatedRoute`
  *
  * @publicApi
  */
@@ -86,10 +87,9 @@ export function createEmptyStateSnapshot(
 }
 
 /**
- * @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.
+ * Provides access to information about a route associated with a component
+ * that is loaded in an outlet.
+ * Use to traverse the `RouterState` tree and extract information from nodes.
  *
  * {@example router/activated-route/module.ts region="activated-route"
  *     header="activated-route.component.ts" linenums="false"}
@@ -98,58 +98,57 @@ export function createEmptyStateSnapshot(
  */
 export class ActivatedRoute {
   /** The current snapshot of this route */
-  // TODO(issue/24571): remove '!'.
   snapshot !: ActivatedRouteSnapshot;
   /** @internal */
   _futureSnapshot: ActivatedRouteSnapshot;
   /** @internal */
-  // TODO(issue/24571): remove '!'.
   _routerState !: RouterState;
   /** @internal */
-  // TODO(issue/24571): remove '!'.
   _paramMap !: Observable<ParamMap>;
   /** @internal */
-  // TODO(issue/24571): remove '!'.
   _queryParamMap !: Observable<ParamMap>;
 
   /** @internal */
   constructor(
-      /** An observable of the URL segments matched by this route */
+      /** An observable of the URL segments matched by this route. */
       public url: Observable<UrlSegment[]>,
-      /** An observable of the matrix parameters scoped to this route */
+      /** An observable of the matrix parameters scoped to this route. */
       public params: Observable<Params>,
-      /** An observable of the query parameters shared by all the routes */
+      /** An observable of the query parameters shared by all the routes. */
       public queryParams: Observable<Params>,
-      /** An observable of the URL fragment shared by all the routes */
+      /** An observable of the URL fragment shared by all the routes. */
       public fragment: Observable<string>,
       /** An observable of the static and resolved data of this route. */
       public data: Observable<Data>,
-      /** The outlet name of the route. It's a constant */
+      /** The outlet name of the route, a constant. */
       public outlet: string,
-      /** The component of the route. It's a constant */
+      /** The component of the route, a constant. */
       // TODO(vsavkin): remove |string
       public component: Type<any>|string|null, futureSnapshot: ActivatedRouteSnapshot) {
     this._futureSnapshot = futureSnapshot;
   }
 
-  /** The configuration used to match this route */
+  /** The configuration used to match this route. */
   get routeConfig(): Route|null { return this._futureSnapshot.routeConfig; }
 
-  /** The root of the router state */
+  /** The root of the router state. */
   get root(): ActivatedRoute { return this._routerState.root; }
 
-  /** The parent of this route in the router state tree */
+  /** The parent of this route in the router state tree. */
   get parent(): ActivatedRoute|null { return this._routerState.parent(this); }
 
-  /** The first child of this route in the router state tree */
+  /** The first child of this route in the router state tree. */
   get firstChild(): ActivatedRoute|null { return this._routerState.firstChild(this); }
 
-  /** The children of this route in the router state tree */
+  /** The children of this route in the router state tree. */
   get children(): ActivatedRoute[] { return this._routerState.children(this); }
 
-  /** The path from the root of the router state tree to this route */
+  /** The path from the root of the router state tree to this route. */
   get pathFromRoot(): ActivatedRoute[] { return this._routerState.pathFromRoot(this); }
 
+  /** An Observable that contains a map of the required and optional parameters
+   * specific to the route.
+   * The map supports retrieving single and multiple values from the same parameter. */
   get paramMap(): Observable<ParamMap> {
     if (!this._paramMap) {
       this._paramMap = this.params.pipe(map((p: Params): ParamMap => convertToParamMap(p)));
@@ -157,6 +156,10 @@ export class ActivatedRoute {
     return this._paramMap;
   }
 
+  /**
+   * An Observable that contains a map of the query parameters available to all routes.
+   * The map supports retrieving single and multiple values from the query parameter.
+   */
   get queryParamMap(): Observable<ParamMap> {
     if (!this._queryParamMap) {
       this._queryParamMap =
diff --git a/packages/router/src/shared.ts b/packages/router/src/shared.ts
index a42ec2eb6c..8a0c4c3b96 100644
--- a/packages/router/src/shared.ts
+++ b/packages/router/src/shared.ts
@@ -11,16 +11,16 @@ import {UrlSegment, UrlSegmentGroup} from './url_tree';
 
 
 /**
- * @description
- *
- * Name of the primary outlet.
+ * The primary routing outlet.
  *
  * @publicApi
  */
 export const PRIMARY_OUTLET = 'primary';
 
 /**
- * A collection of parameters.
+ * A collection of matrix and query URL parameters.
+ * @see `convertToParamMap()`
+ * @see `ParamMap`
  *
  * @publicApi
  */
@@ -29,34 +29,40 @@ export type Params = {
 };
 
 /**
- * Matrix and Query parameters.
+ * A map that provides access to the required and optional parameters
+ * specific to a route.
+ * The map supports retrieving a single value with `get()`
+ * or multiple values with `getAll()`.
  *
- * `ParamMap` makes it easier to work with parameters as they could have either a single value or
- * multiple value. Because this should be known by the user, calling `get` or `getAll` returns the
- * correct type (either `string` or `string[]`).
- *
- * The API is inspired by the URLSearchParams interface.
- * see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+ * @see [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
  *
  * @publicApi
  */
 export interface ParamMap {
+  /**
+   * Reports whether the map contains a given parameter.
+   * @param name The parameter name.
+   * @returns True if the map contains the given parameter, false otherwise.
+   */
   has(name: string): boolean;
   /**
-   * Return a single value for the given parameter name:
-   * - the value when the parameter has a single value,
-   * - the first value if the parameter has multiple values,
-   * - `null` when there is no such parameter.
+   * Retrieves a single value for a parameter.
+   * @param name The parameter name.
+   * @return The parameter's single value,
+   * or the first value if the parameter has multiple values,
+   * or `null` when there is no such parameter.
    */
   get(name: string): string|null;
   /**
-   * Return an array of values for the given parameter name.
+   * Retrieves multiple values for a parameter.
+   * @param name The parameter name.
+   * @return An array containing one or more values,
+   * or an empty array if there is no such parameter.
    *
-   * If there is no such parameter, an empty array is returned.
    */
   getAll(name: string): string[];
 
-  /** Name of the parameters */
+  /** Names of the parameters in the map. */
   readonly keys: string[];
 }
 
@@ -89,7 +95,9 @@ class ParamsAsMap implements ParamMap {
 }
 
 /**
- * Convert a `Params` instance to a `ParamMap`.
+ * Converts a `Params` instance to a `ParamMap`.
+ * @param params The instance to convert.
+ * @returns The new map instance.
  *
  * @publicApi
  */
diff --git a/packages/router/testing/PACKAGE.md b/packages/router/testing/PACKAGE.md
new file mode 100644
index 0000000000..c6721f1b91
--- /dev/null
+++ b/packages/router/testing/PACKAGE.md
@@ -0,0 +1 @@
+Supplies a testing module for the Angular `Router` subsystem.
\ No newline at end of file
diff --git a/packages/router/upgrade/PACKAGE.md b/packages/router/upgrade/PACKAGE.md
new file mode 100644
index 0000000000..f59766ebc0
--- /dev/null
+++ b/packages/router/upgrade/PACKAGE.md
@@ -0,0 +1 @@
+Provides support for upgrading routing applications from Angular JS to Angular.
\ No newline at end of file
diff --git a/packages/router/upgrade/src/upgrade.ts b/packages/router/upgrade/src/upgrade.ts
index e6fd41c888..0e9d482351 100644
--- a/packages/router/upgrade/src/upgrade.ts
+++ b/packages/router/upgrade/src/upgrade.ts
@@ -12,12 +12,12 @@ import {Router} from '@angular/router';
 import {UpgradeModule} from '@angular/upgrade/static';
 
 /**
- * @description
+ * Creates an initializer that sets up `ngRoute` integration
+ * along with setting up the Angular router.
  *
- * Creates an initializer that in addition to setting up the Angular
- * router sets up the ngRoute integration.
+ * @usageNotes
  *
- * ```
+ * <code-example language="typescript" linenums="false">
  * @NgModule({
  *  imports: [
  *   RouterModule.forRoot(SOME_ROUTES),
@@ -30,7 +30,7 @@ import {UpgradeModule} from '@angular/upgrade/static';
  * export class AppModule {
  *   ngDoBootstrap() {}
  * }
- * ```
+ * </code-example>
  *
  * @publicApi
  */
@@ -49,12 +49,14 @@ export function locationSyncBootstrapListener(ngUpgrade: UpgradeModule) {
 }
 
 /**
- * @description
+ * Sets up a location change listener to trigger `history.pushState`.
+ * Works around the problem that `onPopState` does not trigger `history.pushState`.
+ * Must be called *after* calling `UpgradeModule.bootstrap`.
  *
- * 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
+ * @param ngUpgrade The upgrade NgModule.
+ * @param urlType The location strategy.
+ * @see `HashLocationStrategy`
+ * @see `PathLocationStrategy`
  *
  * @publicApi
  */
@@ -87,7 +89,7 @@ export function setUpLocationSync(ngUpgrade: UpgradeModule, urlType: 'path' | 'h
 }
 
 /**
- * Normalize and parse a URL.
+ * Normalizes and parses a URL.
  *
  * - Normalizing means that a relative URL will be resolved into an absolute URL in the context of
  *   the application document.
diff --git a/tools/public_api_guard/router/router.d.ts b/tools/public_api_guard/router/router.d.ts
index 7d138b7b54..109e4536b4 100644
--- a/tools/public_api_guard/router/router.d.ts
+++ b/tools/public_api_guard/router/router.d.ts
@@ -255,6 +255,8 @@ export declare const PRIMARY_OUTLET = "primary";
 
 export declare function provideRoutes(routes: Routes): any;
 
+export declare type QueryParamsHandling = 'merge' | 'preserve' | '';
+
 export interface Resolve<T> {
     resolve(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<T> | Promise<T> | T;
 }