docs(router): add api docs

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

@@ -13,32 +13,46 @@ import {Router} from '../router';
 import {ActivatedRoute} from '../router_state';
 import {UrlTree} from '../url_tree';
 
-
-
 /**
  * The RouterLink directive lets you link to specific parts of your app.
  *
  * Consider the following route configuration:
 
  * ```
- * [{ path: '/user', component: UserCmp }]
+ * [{ path: 'user/:name', component: UserCmp }]
  * ```
  *
  * When linking to this `User` route, you can write:
  *
  * ```
- * <a [routerLink]="['/user']">link to user component</a>
+ * <a [routerLink]="/user/bob">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`.
+ * If you use dynamic values to generate the link, you can pass an array of path
+ * segments, followed by the params for each segment.
  *
- * 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 level.
+ * For instance `['/team', teamId, 'user', userName, {details: true}]`
+ * means that we want to generate a link to `/team/11/user/bob;details=true`.
+ * Multiple static segments can be merged into one (e.g., `['/team/11/user', userName, {details:
+ true}]`).
+ *
+ * The first segment name can be prepended with `/`, `./`, or `../`:
+ * * If the first segment begins with `/`, the router will look up the route from the root of the
+ app.
+ * * If the first segment begins with `./`, or doesn't begin with a slash, the router will
+ * instead look in the children of the current activated route.
+ * * And if the first segment begins with `../`, the router will go up one level.
+ *
+ * You can set query params and fragment as follows:
+ *
+ * ```
+ * <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" fragment="education">link to user
+ component</a>
+ * ```
+ *
+ * RouterLink will use these to generate this link: `/user/bob#education?debug=true`.
+ *
+ * @stable
  */
 @Directive({selector: '[routerLink]'})
 export class RouterLink implements OnChanges {

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

@@ -14,17 +14,55 @@ import {containsTree} from '../url_tree';
 
 import {RouterLink} from './router_link';
 
-interface RouterLinkActiveOptions {
-  exact: boolean;
-}
-
+/**
+ * The RouterLinkActive directive lets you add a CSS class to an element when the link's route
+ * becomes active.
+ *
+ * Consider the following example:
+ *
+ * ```
+ * <a [routerLink]="/user/bob" routerLinkActive="active-link">Bob</a>
+ * ```
+ *
+ * When the url is either '/user' or '/user/bob', the active-link class will
+ * be added to the `a` tag. If the url changes, the class will be removed.
+ *
+ * You can set more than one class, as follows:
+ *
+ * ```
+ * <a [routerLink]="/user/bob" routerLinkActive="class1 class2">Bob</a>
+ * <a [routerLink]="/user/bob" routerLinkActive="['class1', 'class2']">Bob</a>
+ * ```
+ *
+ * You can configure RouterLinkActive by passing `exact: true`. This will add the classes
+ * only when the url matches the link exactly.
+ *
+ * ```
+ * <a [routerLink]="/user/bob" routerLinkActive="active-link" [routerLinkActiveOptions]="{exact:
+ * true}">Bob</a>
+ * ```
+ *
+ * Finally, you can apply the RouterLinkActive directive to an ancestor of a RouterLink.
+ *
+ * ```
+ * <div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
+ *   <a [routerLink]="/user/jim">Jim</a>
+ *   <a [routerLink]="/user/bob">Bob</a>
+ * </div>
+ * ```
+ *
+ * This will set the active-link class on the div tag if the url is either '/user/jim' or
+ * '/user/bob'.
+ *
+ * @stable
+ */
 @Directive({selector: '[routerLinkActive]'})
 export class RouterLinkActive implements OnChanges, OnDestroy, AfterContentInit {
   @ContentChildren(RouterLink) private links: QueryList<RouterLink>;
   private classes: string[] = [];
   private subscription: Subscription;
 
-  @Input() private routerLinkActiveOptions: RouterLinkActiveOptions = {exact: false};
+  @Input() private routerLinkActiveOptions: {exact: boolean} = {exact: false};
 
   /**
    * @internal

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

@@ -12,6 +12,19 @@ import {RouterOutletMap} from '../router_outlet_map';
 import {ActivatedRoute} from '../router_state';
 import {PRIMARY_OUTLET} from '../shared';
 
+/**
+ * A router outlet is a placeholder that Angular dynamically fills based on the application's route.
+ *
+ * ## Use
+ *
+ * ```
+ * <router-outlet></router-outlet>
+ * <router-outlet name="left"></router-outlet>
+ * <router-outlet name="right"></router-outlet>
+ * ```
+ *
+ * @stable
+ */
 @Directive({selector: 'router-outlet'})
 export class RouterOutlet {
   private activated: ComponentRef<any>;
@@ -61,8 +74,10 @@ export class RouterOutlet {
     } catch (e) {
       if (!(e instanceof NoComponentFactoryError)) throw e;
       const componentName = component ? component.name : null;
+
       console.warn(
-          `No component factory found for '${componentName}'. Add '${componentName}' to the 'precompile' list of your application component. This will be required in a future release of the router.`);
+          `'${componentName}' not found in precompile array.  To ensure all components referred to by the RouterConfig are compiled, you must add '${componentName}' to the 'precompile' array of your application component. This will be required in a future release of the router.`);
+
       factory = snapshot._resolvedComponentFactory;
     }