docs(router): improve docs for Instruction and related classes

Closes #4303

modules/angular2/src/router/instruction.ts

@@ -11,6 +11,37 @@ import {Promise} from 'angular2/src/core/facade/async';
 import {PathRecognizer} from './path_recognizer';
 import {Url} from './url_parser';
 
+/**
+ * `RouteParams` is an immutable map of parameters for the given route
+ * based on the url matcher and optional parameters for that route.
+ *
+ * You can inject `RouteParams` into the constructor of a component to use it.
+ *
+ * ## Example
+ *
+ * ```
+ * import {bootstrap, Component, View} from 'angular2/angular2';
+ * import {Router, ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router';
+ *
+ * @Component({...})
+ * @View({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  {path: '/user/:id', component: UserCmp, as: 'UserCmp'},
+ * ])
+ * class AppCmp {}
+ *
+ * @Component({...})
+ * @View({ template: 'user: {{id}}' })
+ * class UserCmp {
+ *   string: id;
+ *   constructor(params: RouteParams) {
+ *     this.id = params.get('id');
+ *   }
+ * }
+ *
+ * bootstrap(AppCmp, routerBindings(AppCmp));
+ * ```
+ */
 export class RouteParams {
   constructor(public params: StringMap<string, string>) {}
 
@@ -18,15 +49,41 @@ export class RouteParams {
 }
 
 /**
- * `Instruction` is a tree of `ComponentInstructions`, with all the information needed
+ * `Instruction` is a tree of {@link ComponentInstruction}s with all the information needed
  * to transition each component in the app to a given route, including all auxiliary routes.
  *
- * This is a public API.
+ * `Instruction`s can be created using {@link Router#generate}, and can be used to
+ * perform route changes with {@link Router#navigateByInstruction}.
+ *
+ * ## Example
+ *
+ * ```
+ * import {bootstrap, Component, View} from 'angular2/angular2';
+ * import {Router, ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router';
+ *
+ * @Component({...})
+ * @View({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  {...},
+ * ])
+ * class AppCmp {
+ *   constructor(router: Router) {
+ *     var instruction = router.generate(['/MyRoute']);
+ *     router.navigateByInstruction(instruction);
+ *   }
+ * }
+ *
+ * bootstrap(AppCmp, routerBindings(AppCmp));
+ * ```
  */
 export class Instruction {
   constructor(public component: ComponentInstruction, public child: Instruction,
               public auxInstruction: StringMap<string, Instruction>) {}
 
+  /**
+   * Returns a new instruction that shares the state of the existing instruction, but with
+   * the given child {@link Instruction} replacing the existing child.
+   */
   replaceChild(child: Instruction): Instruction {
     return new Instruction(this.component, child, this.auxInstruction);
   }
@@ -85,8 +142,7 @@ function stringifyAux(instruction: Instruction): string {
  *
  * `ComponentInstruction`s are [https://en.wikipedia.org/wiki/Hash_consing](hash consed). You should
  * never construct one yourself with "new." Instead, rely on {@link Router/PathRecognizer} to
- * construct
+ * construct `ComponentInstruction`s.
- * `ComponentInstruction`s.
  *
  * You should not modify this object. It should be treated as immutable.
  */
@@ -99,13 +155,33 @@ export class ComponentInstruction {
   constructor(public urlPath: string, public urlParams: string[],
               private _recognizer: PathRecognizer, public params: StringMap<string, any> = null) {}
 
+  /**
+   * Returns the component type of the represented route, or `null` if this instruction
+   * hasn't been resolved.
+   */
   get componentType() { return this._recognizer.handler.componentType; }
 
+  /**
+   * Returns a promise that will resolve to component type of the represented route.
+   * If this instruction references an {@link AsyncRoute}, the `loader` function of that route
+   * will run.
+   */
   resolveComponentType(): Promise<Type> { return this._recognizer.handler.resolveComponentType(); }
 
+  /**
+   * Returns the specificity of the route associated with this `Instruction`.
+   */
   get specificity() { return this._recognizer.specificity; }
 
+  /**
+   * Returns `true` if the component type of this instruction has no child {@link RouteConfig},
+   * or `false` if it does.
+   */
   get terminal() { return this._recognizer.terminal; }
 
+  /**
+   * Returns the route data of the given route that was specified in the {@link RouteDefinition},
+   * or `null` if no route data was specified.
+   */
   routeData(): Object { return this._recognizer.handler.data; }
 }