docs(router): improve docs for RouteDefinition classes

btford · btford · commit 5c0a9eff62b4 · 2015-09-23T00:47:15.000Z
diff --git a/modules/angular2/src/router/route_config_impl.ts b/modules/angular2/src/router/route_config_impl.ts
@@ -3,20 +3,35 @@ import {RouteDefinition} from './route_definition';
 export {RouteDefinition} from './route_definition';
 
 /**
- * You use the RouteConfig annotation to add routes to a component.
+ * The `RouteConfig` decorator defines routes for a given component.
  *
- * Supported keys:
- * - `path` (required)
- * - `component`, `loader`,  `redirectTo` (requires exactly one of these)
- * - `as` (optional)
- * - `data` (optional)
+ * It takes an array of {@link RouteDefinition}s.
  */
 @CONST()
 export class RouteConfig {
   constructor(public configs: RouteDefinition[]) {}
 }
 
-
+/**
+ * `Route` is a type of {@link RouteDefinition} used to route a path to a component.
+ *
+ * It has the following properties:
+ * - `path` is a string that uses the route matcher DSL.
+ * - `component` a component type.
+ * - `as` is an optional `CamelCase` string representing the name of the route.
+ * - `data` is an optional property of any type representing arbitrary route metadata for the given
+ * route. It is injectable via the {@link ROUTE_DATA} token.
+ *
+ * ## Example
+ * ```
+ * import {RouteConfig} from 'angular2/router';
+ *
+ * @RouteConfig([
+ *   {path: '/home', component: HomeCmp, as: 'HomeCmp' }
+ * ])
+ * class MyApp {}
+ * ```
+ */
 @CONST()
 export class Route implements RouteDefinition {
   data: any;
@@ -37,8 +52,26 @@ export class Route implements RouteDefinition {
   }
 }
 
-
-
+/**
+ * `AuxRoute` is a type of {@link RouteDefinition} used to define an auxiliary route.
+ *
+ * It takes an object with the following properties:
+ * - `path` is a string that uses the route matcher DSL.
+ * - `component` a component type.
+ * - `as` is an optional `CamelCase` string representing the name of the route.
+ * - `data` is an optional property of any type representing arbitrary route metadata for the given
+ * route. It is injectable via the {@link ROUTE_DATA} token.
+ *
+ * ## Example
+ * ```
+ * import {RouteConfig, AuxRoute} from 'angular2/router';
+ *
+ * @RouteConfig([
+ *   new AuxRoute({path: '/home', component: HomeCmp})
+ * ])
+ * class MyApp {}
+ * ```
+ */
 @CONST()
 export class AuxRoute implements RouteDefinition {
   data: any = null;
@@ -55,6 +88,27 @@ export class AuxRoute implements RouteDefinition {
   }
 }
 
+/**
+ * `AsyncRoute` is a type of {@link RouteDefinition} used to route a path to an asynchronously
+ * loaded component.
+ *
+ * It has the following properties:
+ * - `path` is a string that uses the route matcher DSL.
+ * - `loader` is a function that returns a promise that resolves to a component.
+ * - `as` is an optional `CamelCase` string representing the name of the route.
+ * - `data` is an optional property of any type representing arbitrary route metadata for the given
+ * route. It is injectable via the {@link ROUTE_DATA} token.
+ *
+ * ## Example
+ * ```
+ * import {RouteConfig} from 'angular2/router';
+ *
+ * @RouteConfig([
+ *   {path: '/home', loader: () => Promise.resolve(MyLoadedCmp), as: 'MyLoadedCmp'}
+ * ])
+ * class MyApp {}
+ * ```
+ */
 @CONST()
 export class AsyncRoute implements RouteDefinition {
   data: any;
@@ -69,6 +123,25 @@ export class AsyncRoute implements RouteDefinition {
   }
 }
 
+/**
+ * `Redirect` is a type of {@link RouteDefinition} used to route a path to an asynchronously loaded
+ * component.
+ *
+ * It has the following properties:
+ * - `path` is a string that uses the route matcher DSL.
+ * - `redirectTo` is a string representing the new URL to be matched against.
+ *
+ * ## Example
+ * ```
+ * import {RouteConfig} from 'angular2/router';
+ *
+ * @RouteConfig([
+ *   {path: '/', redirectTo: '/home'},
+ *   {path: '/home', component: HomeCmp}
+ * ])
+ * class MyApp {}
+ * ```
+ */
 @CONST()
 export class Redirect implements RouteDefinition {
   path: string;
diff --git a/modules/angular2/src/router/route_definition.ts b/modules/angular2/src/router/route_definition.ts
@@ -1,5 +1,16 @@
 import {CONST, Type} from 'angular2/src/core/facade/lang';
 
+/**
+ * `RouteDefinition` defines a route within a {@link RouteConfig} decorator.
+ *
+ * Supported keys:
+ * - `path` (required)
+ * - `component`, `loader`,  `redirectTo` (requires exactly one of these)
+ * - `as` (optional)
+ * - `data` (optional)
+ *
+ * See also {@link Route}, {@link AsyncRoute}, {@link AuxRoute}, and {@link Redirect}.
+ */
 export interface RouteDefinition {
   path: string;
   component?: Type | ComponentDefinition;
