From 5bf1c93ead4cd24473477f17e410f6f2db4bc674 Mon Sep 17 00:00:00 2001
From: vsavkin <avix1000@gmail.com>
Date: Tue, 24 May 2016 13:41:37 -0700
Subject: [PATCH] docs: adds missing api docs

---
 modules/@angular/router/src/router.ts       | 36 +++++++++++++++++++
 modules/@angular/router/src/router_state.ts | 38 +++++++++++++++++++--
 modules/@angular/router/src/url_tree.ts     |  3 ++
 3 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/modules/@angular/router/src/router.ts b/modules/@angular/router/src/router.ts
index b094931ce5..9252a290f8 100644
--- a/modules/@angular/router/src/router.ts
+++ b/modules/@angular/router/src/router.ts
@@ -11,22 +11,58 @@ import { RouterOutlet } from './directives/router_outlet';
 import { forEach } from './util';
 import { Subscription } from 'rxjs/Subscription';
 
+/**
+ * The `Router` is responsible for mapping URLs to components.
+ */
 export class Router {
   private currentState: RouterState;
   private config: RouterConfig;
   private locationSubscription: Subscription;
 
+  /**
+   * @internal
+   */
   constructor(private rootComponent:Object, private resolver: ComponentResolver, private urlSerializer: UrlSerializer, private outletMap: RouterOutletMap, private location: Location) {
     this.currentState = createEmptyState(<any>rootComponent.constructor);
     this.setUpLocationChangeListener();
     this.navigateByUrl(this.location.path());
   }
 
+  /**
+   * Returns the current route state.
+   */
+  get routerState(): RouterState {
+    return this.currentState;
+  }
+
+  /**
+   * Navigate based on the provided url. This navigation is always absolute.
+   *
+   * ### Usage
+   *
+   * ```
+   * router.navigateByUrl("/team/33/user/11");
+   * ```
+   */
   navigateByUrl(url: string): void {
     const urlTree = this.urlSerializer.parse(url);
     this.navigate(urlTree, false);
   }
 
+  /**
+   * Resets the configuration used for navigation and generating links.
+   *
+   * ### Usage
+   *
+   * ```
+   * router.resetConfig([
+   *  { name: 'team', path: 'team/:id', component: TeamCmp, children: [
+   *    { name: 'simple', path: 'simple', component: SimpleCmp },
+   *    { name: 'user', path: 'user/:name', component: UserCmp }
+   *  ] }
+   * ]);
+   * ```
+   */
   resetConfig(config: RouterConfig): void {
     this.config = config;
   }
diff --git a/modules/@angular/router/src/router_state.ts b/modules/@angular/router/src/router_state.ts
index b32c2917c2..456f175333 100644
--- a/modules/@angular/router/src/router_state.ts
+++ b/modules/@angular/router/src/router_state.ts
@@ -4,10 +4,32 @@ import { Observable } from 'rxjs/Observable';
 import { BehaviorSubject } from 'rxjs/BehaviorSubject';
 import { ComponentFactory, Type } from '@angular/core';
 
+/**
+ * A collection of parameters.
+ */
 export type Params = { [key: string]: string };
 
-export const PRIMARY_OUTLET = "PRIMARY_OUTLET";
+/**
+ * Name of the primary outlet.
+ * @type {string}
+ */
+export const PRIMARY_OUTLET: string = "PRIMARY_OUTLET";
 
+/**
+ * The state of the router at a particular moment in time.
+ *
+ * ### Usage
+ *
+ * ```
+ * class MyComponent {
+ *   constructor(router: Router) {
+ *     const state = router.routerState;
+ *     const id: Observable<string> = state.firstChild(state.root).params.map(p => p.id);
+ *     const isDebug: Observable<string> = state.queryParams.map(q => q.debug);
+ *   }
+ * }
+ * ```
+ */
 export class RouterState extends Tree<ActivatedRoute> {
   constructor(root: TreeNode<ActivatedRoute>, public queryParams: Observable<Params>, public fragment: Observable<string>) {
     super(root);
@@ -19,11 +41,23 @@ export function createEmptyState(rootComponent: Type): RouterState {
   const emptyParams = new BehaviorSubject({});
   const emptyQueryParams = new BehaviorSubject({});
   const fragment = new BehaviorSubject("");
-  // TODO outlet name should not be outlet
   const activated = new ActivatedRoute(emptyUrl, emptyParams, PRIMARY_OUTLET, rootComponent, <any>null);
   return new RouterState(new TreeNode<ActivatedRoute>(activated, []), emptyQueryParams, fragment);
 }
 
+/**
+ * Contains the information about a component loaded in an outlet.
+ *
+ * ### Usage
+ *
+ * ```
+ * class MyComponent {
+ *   constructor(route: ActivatedRoute) {
+ *     const id: Observable<string> = route.params.map(p => p.id);
+ *   }
+ * }
+ * ```
+ */
 export class ActivatedRoute {
   constructor(public urlSegments: Observable<UrlSegment[]>,
               public params: Observable<Params>,
diff --git a/modules/@angular/router/src/url_tree.ts b/modules/@angular/router/src/url_tree.ts
index 1203b363b2..bdfd1b8e81 100644
--- a/modules/@angular/router/src/url_tree.ts
+++ b/modules/@angular/router/src/url_tree.ts
@@ -1,6 +1,9 @@
 import { Tree, TreeNode } from './tree';
 import { shallowEqual } from './util';
 
+/**
+ * A URL in the tree form.
+ */
 export class UrlTree extends Tree<UrlSegment> {
   constructor(root: TreeNode<UrlSegment>, public queryParameters: {[key: string]: string}, public fragment: string | null) {
     super(root);