From fa2c6791b4c0b98e00b213e33751e082aee9c44b Mon Sep 17 00:00:00 2001
From: Brian Ford <btford@umich.edu>
Date: Sun, 30 Aug 2015 20:36:21 -0700
Subject: [PATCH] docs(router): improve docs for RouterOutlet methods

Closes #3909
---
 modules/angular2/src/router/router_outlet.ts | 30 ++++++++++++++++++--
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/modules/angular2/src/router/router_outlet.ts b/modules/angular2/src/router/router_outlet.ts
index 9a5585c554..c0ceee72bb 100644
--- a/modules/angular2/src/router/router_outlet.ts
+++ b/modules/angular2/src/router/router_outlet.ts
@@ -40,6 +40,10 @@ export class RouterOutlet {
     }
   }
 
+  /**
+   * Called by the Router to instantiate a new component during the commit phase of a navigation.
+   * This method in turn is responsible for calling the `onActivate` hook of its child.
+   */
   activate(nextInstruction: ComponentInstruction): Promise<any> {
     var previousInstruction = this._currentInstruction;
     this._currentInstruction = nextInstruction;
@@ -61,6 +65,11 @@ export class RouterOutlet {
         });
   }
 
+  /**
+   * Called by the {@link Router} during the commit phase of a navigation when an outlet
+   * reuses a component between different routes.
+   * This method in turn is responsible for calling the `onReuse` hook of its child.
+   */
   reuse(nextInstruction: ComponentInstruction): Promise<any> {
     var previousInstruction = this._currentInstruction;
     this._currentInstruction = nextInstruction;
@@ -74,6 +83,10 @@ export class RouterOutlet {
             true);
   }
 
+  /**
+   * Called by the {@link Router} when an outlet reuses a component across navigations.
+   * This method in turn is responsible for calling the `onReuse` hook of its child.
+   */
   deactivate(nextInstruction: ComponentInstruction): Promise<any> {
     var next = _resolveToTrue;
     if (isPresent(this._componentRef) && isPresent(this._currentInstruction) &&
@@ -90,7 +103,12 @@ export class RouterOutlet {
   }
 
   /**
-   * Called by Router during recognition phase
+   * Called by the {@link Router} during recognition phase of a navigation.
+   *
+   * If this resolves to `false`, the given navigation is cancelled.
+   *
+   * This method delegates to the child component's `canDeactivate` hook if it exists,
+   * and otherwise resolves to true.
    */
   canDeactivate(nextInstruction: ComponentInstruction): Promise<boolean> {
     if (isBlank(this._currentInstruction)) {
@@ -103,9 +121,15 @@ export class RouterOutlet {
     return _resolveToTrue;
   }
 
-
   /**
-   * Called by Router during recognition phase
+   * Called by the {@link Router} during recognition phase of a navigation.
+   *
+   * If the new child component has a different Type than the existing child component,
+   * this will resolve to `false`. You can't reuse an old component when the new component
+   * is of a different Type.
+   *
+   * Otherwise, this method delegates to the child component's `canReuse` hook if it exists,
+   * or resolves to true if the hook is not present.
    */
   canReuse(nextInstruction: ComponentInstruction): Promise<boolean> {
     var result;