From f2c6157e7482d61a06c68a731dc8085ea6b03292 Mon Sep 17 00:00:00 2001
From: vsavkin <avix1000@gmail.com>
Date: Sat, 10 Sep 2016 16:53:27 -0700
Subject: [PATCH] docs(router): update docs of RouteModule and
 RouterTestingModule

---
 modules/@angular/router/src/router_module.ts  | 100 +++++++++++++++---
 .../router/testing/router_testing_module.ts   |  40 ++++++-
 2 files changed, 120 insertions(+), 20 deletions(-)

diff --git a/modules/@angular/router/src/router_module.ts b/modules/@angular/router/src/router_module.ts
index 2bffc26636..526bff56aa 100644
--- a/modules/@angular/router/src/router_module.ts
+++ b/modules/@angular/router/src/router_module.ts
@@ -23,15 +23,20 @@ import {flatten} from './utils/collection';
 
 
 /**
+ * @whatItDoes Contains a list of directives
  * @stable
  */
 const ROUTER_DIRECTIVES = [RouterOutlet, RouterLink, RouterLinkWithHref, RouterLinkActive];
 
 /**
+ * @whatItDoes Is used in DI to configure router.
  * @stable
  */
 export const ROUTER_CONFIGURATION = new OpaqueToken('ROUTER_CONFIGURATION');
 
+/**
+ * @docsNotRequired
+ */
 export const ROUTER_FORROOT_GUARD = new OpaqueToken('ROUTER_FORROOT_GUARD');
 
 const pathLocationStrategy = {
@@ -58,33 +63,72 @@ export const ROUTER_PROVIDERS: Provider[] = [
 ];
 
 /**
- * Router module.
+ * @whatItDoes Adds router directives and providers.
  *
- * When registered at the root, it should be used as follows:
+ * @howToUse
  *
- * ### Example
+ * RouterModule can be imported multiple times: once per lazily-loaded bundle.
+ * Since the router deals with a global shared resource--location, we cannot have
+ * more than one router service active.
  *
- * ```
- * bootstrap(AppCmp, {imports: [RouterModule.forRoot(ROUTES)]});
- * ```
+ * That is why there are two ways to create the module: `RouterModule.forRoot` and
+ * `RouterModule.forChild`.
  *
- * For submodules and lazy loaded submodules it should be used as follows:
+ * * `forRoot` creates a module that contains all the directives, the given routes, and the router
+ * service itself.
+ * * `forChild` creates a module that contains all the directives and the given routes, but does not
+ * include
+ * the router service.
  *
- * ### Example
+ * When registered at the root, the module should be used as follows
  *
  * ```
  * @NgModule({
- *   imports: [RouterModule.forChild(CHILD_ROUTES)]
+ *   imports: [RouterModule.forRoot(ROUTES)]
  * })
- * class Lazy {}
+ * class MyNgModule {}
  * ```
  *
+ * For submodules and lazy loaded submodules the module should be used as follows:
+ *
+ * ```
+ * @NgModule({
+ *   imports: [RouterModule.forChild(ROUTES)]
+ * })
+ * class MyNgModule {}
+ * ```
+ *
+ * @description
+ *
+ * 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.
+ * Doing this transparently is not trivial.
+ *
+ * The Angular 2 router 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.
+ *
  * @stable
  */
 @NgModule({declarations: ROUTER_DIRECTIVES, exports: ROUTER_DIRECTIVES})
 export class RouterModule {
   constructor(@Optional() @Inject(ROUTER_FORROOT_GUARD) guard: any) {}
 
+  /**
+   * Creates a module with all the router providers and directives. It also optionally sets up an
+   * application listener to perform an initial navigation.
+   *
+   * Options:
+   * * `enableTracing` makes the router log all its internal 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` provides a custom error handler.
+   */
   static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders {
     return {
       ngModule: RouterModule,
@@ -106,6 +150,9 @@ export class RouterModule {
     };
   }
 
+  /**
+   * Creates a module with all the router directives and a provider registering routes.
+   */
   static forChild(routes: Routes): ModuleWithProviders {
     return {ngModule: RouterModule, providers: [provideRoutes(routes)]};
   }
@@ -126,6 +173,18 @@ export function provideForRootGuard(router: Router): any {
 }
 
 /**
+ * @whatItDoes Registers routes.
+ *
+ * @howToUse
+ *
+ * ```
+ * @NgModule({
+ *   imports: [RouterModule.forChild(ROUTES)],
+ *   providers: [provideRoutes(EXTRA_ROUTES)]
+ * })
+ * class MyNgModule {}
+ * ```
+ *
  * @stable
  */
 export function provideRoutes(routes: Routes): any {
@@ -137,18 +196,29 @@ export function provideRoutes(routes: Routes): any {
 
 
 /**
- * Extra options used to configure the router.
- *
- * Set `enableTracing` to log router events to the console.
- * Set 'useHash' to true to enable HashLocationStrategy.
- * Set `errorHandler` to enable a custom ErrorHandler.
+ * @whatItDoes Represents options to configure the router.
  *
  * @stable
  */
 export interface ExtraOptions {
+  /**
+   * Makes the router log all its internal events to the console.
+   */
   enableTracing?: boolean;
+
+  /**
+   * Enables the location strategy that uses the URL fragment instead of the history API.
+   */
   useHash?: boolean;
+
+  /**
+   * Disables the initial navigation.
+   */
   initialNavigation?: boolean;
+
+  /**
+   * A custom error handler.
+   */
   errorHandler?: ErrorHandler;
 }
 
diff --git a/modules/@angular/router/testing/router_testing_module.ts b/modules/@angular/router/testing/router_testing_module.ts
index 8bd9f37bdc..b799ca0937 100644
--- a/modules/@angular/router/testing/router_testing_module.ts
+++ b/modules/@angular/router/testing/router_testing_module.ts
@@ -14,13 +14,39 @@ import {Route, Router, RouterModule, RouterOutletMap, Routes, UrlSerializer, pro
 import {ROUTER_PROVIDERS, ROUTES, flatten} from './private_import_router';
 
 /**
- * A spy for {@link NgModuleFactoryLoader} that allows tests to simulate the loading of ng module
- * factories.
+ * @whatItDoes Allows to simulate the loading of ng modules in tests.
+ *
+ * @howToUse
+ *
+ * ```
+ * const loader = TestBed.get(NgModuleFactoryLoader);
+ *
+ * @Component({template: 'lazy-loaded'})
+ * class LazyLoadedComponent {}
+ * @NgModule({
+ *   declarations: [LazyLoadedComponent],
+ *   imports: [RouterModule.forChild([{path: 'loaded', component: LazyLoadedComponent}])]
+ * })
+ *
+ * class LoadedModule {}
+ *
+ * // sets up stubbedModules
+ * loader.stubbedModules = {lazyModule: LoadedModule};
+ *
+ * router.resetConfig([
+ *   {path: 'lazy', loadChildren: 'lazyModule'},
+ * ]);
+ *
+ * router.navigateByUrl('/lazy/loaded');
+ * ```
  *
  * @stable
  */
 @Injectable()
 export class SpyNgModuleFactoryLoader implements NgModuleFactoryLoader {
+  /**
+   * @docsNotRequired
+   */
   public stubbedModules: {[path: string]: any} = {};
 
   constructor(private compiler: Compiler) {}
@@ -47,10 +73,9 @@ export function setupTestingRouter(
 }
 
 /**
- * A module setting up the router that should be used for testing.
- * It provides spy implementations of Location, LocationStrategy, and NgModuleFactoryLoader.
+ * @whatItDoes Sets up the router to be used for testing.
  *
- * # Example:
+ * @howToUse
  *
  * ```
  * beforeEach(() => {
@@ -64,6 +89,11 @@ export function setupTestingRouter(
  * });
  * ```
  *
+ * @description
+ *
+ * The modules sets up the router to be used for testing.
+ * It provides spy implementations of Location, LocationStrategy, and NgModuleFactoryLoader.
+ *
  * @stable
  */
 @NgModule({