From 6ce7a5a1ea4498485833a37817b5706cb8f2ca89 Mon Sep 17 00:00:00 2001
From: vsavkin <avix1000@gmail.com>
Date: Fri, 3 Jun 2016 14:28:41 -0700
Subject: [PATCH] docs(router): add docs

---
 modules/@angular/router/src/router.ts | 29 +++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/modules/@angular/router/src/router.ts b/modules/@angular/router/src/router.ts
index 7467aada57..9f1e73f185 100644
--- a/modules/@angular/router/src/router.ts
+++ b/modules/@angular/router/src/router.ts
@@ -26,10 +26,26 @@ import {forkJoin} from 'rxjs/observable/forkJoin';
 
 export interface NavigationExtras { relativeTo?: ActivatedRoute; queryParameters?: Params; fragment?: string; }
 
+/**
+ * An event triggered when a navigation starts
+ */
 export class NavigationStart { constructor(public id:number, public url:UrlTree) {} }
+
+/**
+ * An event triggered when a navigation ends successfully
+ */
 export class NavigationEnd { constructor(public id:number, public url:UrlTree) {} }
+
+/**
+ * An event triggered when a navigation is canceled
+ */
 export class NavigationCancel { constructor(public id:number, public url:UrlTree) {} }
+
+/**
+ * An event triggered when a navigation fails due to unexpected error
+ */
 export class NavigationError { constructor(public id:number, public url:UrlTree, public error:any) {} }
+
 export type Event = NavigationStart | NavigationEnd | NavigationCancel | NavigationError;
 
 /**
@@ -68,6 +84,9 @@ export class Router {
     return this.currentUrlTree;
   }
 
+  /**
+   * Returns an observable of route events
+   */
   get events(): Observable<Event> {
     return this.routerEvents;
   }
@@ -75,6 +94,11 @@ export class Router {
   /**
    * Navigate based on the provided url. This navigation is always absolute.
    *
+   * Returns a promise that:
+   * - is resolved with 'true' when navigation succeeds
+   * - is resolved with 'false' when navigation fails
+   * - is rejected when an error happens
+   *
    * ### Usage
    *
    * ```
@@ -150,6 +174,11 @@ export class Router {
    * Navigate based on the provided array of commands and a starting point.
    * If no starting route is provided, the navigation is absolute.
    *
+   * Returns a promise that:
+   * - is resolved with 'true' when navigation succeeds
+   * - is resolved with 'false' when navigation fails
+   * - is rejected when an error happens
+   *
    * ### Usage
    *
    * ```