docs(router): move examples into own file and add tests

Closes #4620

modules/angular2/src/router/interfaces.ts

@@ -22,20 +22,7 @@ var __ignore_me = global;
  * instantiate and activate child components.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {OnActivate, ComponentInstruction} from 'angular2/router';
- *
- * @Component({
- *   selector: 'my-cmp',
- *   template: '<div>hello!</div>'
- * })
- * class MyCmp implements OnActivate {
- *   onActivate(next: ComponentInstruction, prev: ComponentInstruction) {
- *     this.log = 'Finished navigating from ' + prev.urlPath + ' to ' + next.urlPath;
- *   }
- * }
- * ```
+ * {@example router/ts/on_activate/on_activate_example.ts region='onActivate'}
  */
 export interface OnActivate {
   onActivate(nextInstruction: ComponentInstruction, prevInstruction: ComponentInstruction): any;
@@ -53,24 +40,7 @@ export interface OnActivate {
  * previous route or `null`.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {CanReuse, OnReuse, ComponentInstruction} from 'angular2/router';
- *
- * @Component({
- *   selector: 'my-cmp',
- *   template: '<div>hello!</div>'
- * })
- * class MyCmp implements CanReuse, OnReuse {
- *   canReuse(next: ComponentInstruction, prev: ComponentInstruction) {
- *     return true;
- *   }
- *
- *   onReuse(next: ComponentInstruction, prev: ComponentInstruction) {
- *     this.params = next.params;
- *   }
- * }
- * ```
+ * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
  */
 export interface OnReuse {
   onReuse(nextInstruction: ComponentInstruction, prevInstruction: ComponentInstruction): any;
@@ -87,20 +57,7 @@ export interface OnReuse {
  * If `onDeactivate` returns a promise, the route change will wait until the promise settles.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {OnDeactivate, ComponentInstruction} from 'angular2/router';
- *
- * @Component({
- *   selector: 'my-cmp',
- *   template: '<div>hello!</div>'
- * })
- * class MyCmp implements OnDeactivate {
- *   onDeactivate(next: ComponentInstruction, prev: ComponentInstruction) {
- *     return this.doFadeAwayAnimation();
- *   }
- * }
- *  ```
+ * {@example router/ts/on_deactivate/on_deactivate_example.ts region='onDeactivate'}
  */
 export interface OnDeactivate {
   onDeactivate(nextInstruction: ComponentInstruction, prevInstruction: ComponentInstruction): any;
@@ -122,24 +79,7 @@ export interface OnDeactivate {
  * If `canReuse` throws or rejects, the navigation will be cancelled.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {CanReuse, OnReuse, ComponentInstruction} from 'angular2/router';
- *
- * @Component({
- *   selector: 'my-cmp',
- *   template: '<div>hello!</div>'
- * })
- * class MyCmp implements CanReuse, OnReuse {
- *   canReuse(next: ComponentInstruction, prev: ComponentInstruction) {
- *     return next.params.id == prev.params.id;
- *   }
- *
- *   onReuse(next: ComponentInstruction, prev: ComponentInstruction) {
- *     this.id = next.params.id;
- *   }
- * }
- *  ```
+ * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
  */
 export interface CanReuse {
   canReuse(nextInstruction: ComponentInstruction, prevInstruction: ComponentInstruction): any;
@@ -160,20 +100,7 @@ export interface CanReuse {
  * If `canDeactivate` throws or rejects, the navigation is also cancelled.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {CanDeactivate, ComponentInstruction} from 'angular2/router';
- *
- * @Component({
- *   selector: 'my-cmp',
- *   template: '<div>hello!</div>'
- * })
- * class MyCmp implements CanDeactivate {
- *   canDeactivate(next: ComponentInstruction, prev: ComponentInstruction) {
- *     return askUserIfTheyAreSureTheyWantToQuit();
- *   }
- * }
- *  ```
+ * {@example router/ts/can_deactivate/can_deactivate_example.ts region='canDeactivate'}
  */
 export interface CanDeactivate {
   canDeactivate(nextInstruction: ComponentInstruction, prevInstruction: ComponentInstruction): any;

modules/angular2/src/router/lifecycle_annotations.ts

@@ -20,13 +20,18 @@ export {
  * Defines route lifecycle hook `CanActivate`, which is called by the router to determine
  * if a component can be instantiated as part of a navigation.
  *
- * The `CanActivate` hook is called with two {@link ComponentInstruction}s as parameters, the first
- * representing
- * the current route being navigated to, and the second parameter representing the previous route or
- * `null`.
- *
+ * <aside class="is-right">
  * Note that unlike other lifecycle hooks, this one uses an annotation rather than an interface.
  * This is because the `CanActivate` function is called before the component is instantiated.
+ * </aside>
+ *
+ * The `CanActivate` hook is called with two {@link ComponentInstruction}s as parameters, the first
+ * representing the current route being navigated to, and the second parameter representing the
+ * previous route or `null`.
+ *
+ * ```typescript
+ * @CanActivate((next, prev) => boolean | Promise<boolean>)
+ * ```
  *
  * If `CanActivate` returns or resolves to `false`, the navigation is cancelled.
  * If `CanActivate` throws or rejects, the navigation is also cancelled.
@@ -34,19 +39,8 @@ export {
  * instantiated, and the {@link OnActivate} hook of that component is called if implemented.
  *
  * ### Example
- * ```
- * import {Component} from 'angular2/angular2';
- * import {CanActivate} from 'angular2/router';
  *
- * @Component({
- *   selector: 'control-panel-cmp',
- *   template: '<div>Control Panel: ...</div>'
- * })
- * @CanActivate(() => checkIfUserIsLoggedIn())
- * class ControlPanelCmp {
- *   // ...
- * }
- *  ```
+ * {@example router/ts/can_activate/can_activate_example.ts region='canActivate' }
  */
 export var CanActivate:
     (hook: (next: ComponentInstruction, prev: ComponentInstruction) => Promise<boolean>| boolean) =>