docs(router): add api docs

modules/@angular/router/src/directives/router_link.ts

@@ -19,16 +19,49 @@ import {RouteSegment, UrlSegment, Tree} from '../segments';
 import {isString, isArray, isPresent} from '../facade/lang';
 import {ObservableWrapper} from '../facade/async';
 
+/**
+ * The RouterLink directive lets you link to specific parts of your app.
+ *
+ * Consider the following route configuration:
+
+ * ```
+ * @Routes([
+ *   { path: '/user', component: UserCmp }
+ * ]);
+ * class MyComp {}
+ * ```
+ *
+ * When linking to this `User` route, you can write:
+ *
+ * ```
+ * <a [routerLink]="['/user']">link to user component</a>
+ * ```
+ *
+ * RouterLink expects the value to be an array of path segments, followed by the params
+ * for that level of routing. For instance `['/team', {teamId: 1}, 'user', {userId: 2}]`
+ * means that we want to generate a link to `/team;teamId=1/user;userId=2`.
+ *
+ * The first segment name can be prepended with `/`, `./`, or `../`.
+ * If the segment begins with `/`, the router will look up the route from the root of the app.
+ * If the segment begins with `./`, or doesn't begin with a slash, the router will
+ * instead look in the current component's children for the route.
+ * And if the segment begins with `../`, the router will go up one segment in the url.
+ *
+ * See {@link Router.createUrlTree} for more information.
+ */
 @Directive({selector: '[routerLink]'})
 export class RouterLink implements OnDestroy {
   @Input() target: string;
   private _commands: any[] = [];
   private _subscription: any;
 
+  // the url displayed on the anchor element.
   @HostBinding() href: string;
   @HostBinding('class.router-link-active') isActive: boolean = false;
 
   constructor(@Optional() private _routeSegment: RouteSegment, private _router: Router) {
+    // because auxiliary links take existing primary and auxiliary routes into account,
+    // we need to update the link whenever params or other routes change.
     this._subscription =
         ObservableWrapper.subscribe(_router.changes, (_) => { this._updateTargetUrlAndHref(); });
   }
@@ -48,6 +81,7 @@ export class RouterLink implements OnDestroy {
 
   @HostListener("click")
   onClick(): boolean {
+    // If no target, or if target is _self, prevent default browser behavior
     if (!isString(this.target) || this.target == '_self') {
       this._router.navigate(this._commands, this._routeSegment);
       return false;

modules/@angular/router/src/directives/router_outlet.ts

@@ -13,6 +13,21 @@ import {RouterOutletMap} from '../router';
 import {DEFAULT_OUTLET_NAME} from '../constants';
 import {isPresent, isBlank} from '../facade/lang';
 
+/**
+ * A router outlet is a placeholder that Angular dynamically fills based on the application's route.
+ *
+ * ## Use
+ *
+ * ```
+ * <router-outlet></router-outlet>
+ * ```
+ *
+ * Outlets can be named.
+ *
+ * ```
+ * <router-outlet name="right"></router-outlet>
+ * ```
+ */
 @Directive({selector: 'router-outlet'})
 export class RouterOutlet {
   private _loaded: ComponentRef<any>;
@@ -28,10 +43,19 @@ export class RouterOutlet {
     this._loaded = null;
   }
 
+  /**
+   * Returns the loaded component.
+   */
   get loadedComponent(): Object { return isPresent(this._loaded) ? this._loaded.instance : null; }
 
+  /**
+   * Returns true is the outlet is not empty.
+   */
   get isLoaded(): boolean { return isPresent(this._loaded); }
 
+  /**
+   * Called by the Router to instantiate a new component.
+   */
   load(factory: ComponentFactory<any>, providers: ResolvedReflectiveProvider[],
        outletMap: RouterOutletMap): ComponentRef<any> {
     this.outletMap = outletMap;