docs(router): update docs for router directives

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

@@ -16,7 +16,9 @@ import {UrlTree} from '../url_tree';
 
 
 /**
- * The RouterLink directive lets you link to specific parts of your app.
+ * @whatItDoes Lets you link to specific parts of your app.
+ *
+ * @howToUse
  *
  * Consider the following route configuration:
 
@@ -24,10 +26,20 @@ import {UrlTree} from '../url_tree';
  * [{ path: 'user/:name', component: UserCmp }]
  * ```
  *
- * When linking to this `User` route, you can write:
+ * When linking to this `user/:name` route, you can write:
  *
  * ```
- * <a [routerLink]="/user/bob">link to user component</a>
+ * <a routerLink='/user/bob'>link to user component</a>
+ * ```
+ *
+ * @description
+ *
+ * The RouterLink directives lets you link to specific parts of your app.
+ *
+ * Whe the link is static, you can use the directive as follows:
+ *
+ * ```
+ * <a routerLink="/user/bob">link to user component</a>
  * ```
  *
  * If you use dynamic values to generate the link, you can pass an array of path
@@ -35,6 +47,7 @@ import {UrlTree} from '../url_tree';
  *
  * 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}]`).
  *
@@ -65,7 +78,12 @@ import {UrlTree} from '../url_tree';
  * For instance, if the current url is `/user/(box//aux:team)`.
  *
  * Then the following link `<a [routerLink]="['/user/jim']">Jim</a>` will generate the link
- * `/user/(jim//aux:team)`. See {@link Router.createUrlTree} for more information.
+ * `/user/(jim//aux:team)`.
+ *
+ * @selector ':not(a)[routerLink]'
+ * @ngModule RouterModule
+ *
+ * See {@link Router.createUrlTree} for more information.
  *
  * @stable
  */
@@ -111,7 +129,13 @@ export class RouterLink {
 }
 
 /**
+ * @whatItDoes Lets you link to specific parts of your app.
+ *
  * See {@link RouterLink} for more information.
+ *
+ * @selector 'a[routerLink]'
+ * @ngModule RouterModule
+ *
  * @stable
  */
 @Directive({selector: 'a[routerLink]'})

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

@@ -16,6 +16,16 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
 
 
 /**
+ * @whatItDoes Lets you add a CSS class to an element when the link's route.
+ *
+ * @howToUse
+ *
+ * ```
+ * <a [routerLink]='/user/bob' routerLinkActive='active-link'>Bob</a>
+ * ```
+ *
+ * @description
+ *
  * The RouterLinkActive directive lets you add a CSS class to an element when the link's route
  * becomes active.
  *
@@ -32,7 +42,7 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
  *
  * ```
  * <a [routerLink]="/user/bob" routerLinkActive="class1 class2">Bob</a>
- * <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
@@ -55,6 +65,9 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
  * This will set the active-link class on the div tag if the url is either '/user/jim' or
  * '/user/bob'.
  *
+ * @selector ':not(a)[routerLink]'
+ * @ngModule RouterModule
+ *
  * @stable
  */
 @Directive({selector: '[routerLinkActive]'})

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

@@ -15,25 +15,27 @@ import {PRIMARY_OUTLET} from '../shared';
 
 
 /**
- * A router outlet is a placeholder that Angular dynamically fills based on the application's route.
+ * @whatItDoes Acts as a placeholder that Angular dynamically fills based on the current router
+ * state.
  *
- * ## Example
+ * @howToUse
  *
  * ```
  * <router-outlet></router-outlet>
- * <router-outlet name="left"></router-outlet>
- * <router-outlet name="right"></router-outlet>
+ * <router-outlet name='left'></router-outlet>
+ * <router-outlet name='right'></router-outlet>
  * ```
  *
  * A router outlet will emit an activate event any time a new component is being instantiated,
  * and a deactivate event when it is being destroyed.
  *
- * ## Example
- *
  * ```
- * <router-outlet (activate)="onActivate($event)"
- * (deactivate)="onDeactivate($event)"></router-outlet>
+ * <router-outlet
+ *   (activate)='onActivate($event)'
+ *   (deactivate)='onDeactivate($event)'></router-outlet>
  * ```
+ * @selector 'a[routerLink]'
+ * @ngModule RouterModule
  *
  * @stable
  */