From a30986bdac4978d83495a45aa95e1b583dece6f5 Mon Sep 17 00:00:00 2001
From: Naomi Black <naomitraveller@gmail.com>
Date: Fri, 10 Oct 2014 13:06:41 -0700
Subject: [PATCH] chore(docs): Added missing docs for a few route entries

---
 lib/routing/module.dart  | 25 +++++++++++++++----------
 lib/routing/ng_view.dart |  4 ++--
 lib/routing/routing.dart | 13 ++++++++++++-
 3 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/lib/routing/module.dart b/lib/routing/module.dart
index b57a5e60e..bf350bd99 100644
--- a/lib/routing/module.dart
+++ b/lib/routing/module.dart
@@ -73,7 +73,7 @@
  *        }
  *      }
  *
- *  [RouteProvider] and [Route] can be used to control navigation, specifically,
+ *  [RouteProvider] and `Route` can be used to control navigation, specifically,
  *  leaving of the route. For example, let's consider "edit recipe" component:
  *
  *      @Component(...)
@@ -96,16 +96,16 @@
  *        }
  *      }
  *
- *  [Route.onPreLeave] event is triggered when the browser is routed from an
+ *  `Route.onPreLeave` event is triggered when the browser is routed from an
  *  active route to a different route. The active route can delay and
- *  potentially veto the navigation by passing a [Future<bool>] to
- *  [RoutePreLeaveEvent.allowLeave].
+ *  potentially veto the navigation by passing a `Future<bool>` to
+ *  `RoutePreLeaveEvent.allowLeave`.
  *
- *  Notice that we create a [RouteHandle] for our route. [RouteHandle] are
- *  a convenient wrapper around [Route] that makes unsubscribing route events
+ *  Notice that we create a [RouteHandle] for our route. `RouteHandle` are
+ *  a convenient wrapper around `Route` that makes unsubscribing route events
  *  easier. For example, notice that we didn't need to manually call
- *  [StreamSubscription.cancel] for subscription to [Route.onPreLeave]. Calling
- *  [RouteHandle.discard] unsubscribes all listeners created for the handle.
+ *  `StreamSubscription.cancel` for subscription to `Route.onPreLeave`. Calling
+ *  `RouteHandle.discard` unsubscribes all listeners created for the handle.
  *
  * ## Hierarchical Routes
  *
@@ -142,6 +142,11 @@ part 'routing.dart';
 part 'ng_view.dart';
 part 'ng_bind_route.dart';
 
+/**
+ * A module that defines all necessary bindings for Angular routing. This
+ * module is included in [AngularModule] and typically you don't need to
+ * install it manually.
+ */
 class RoutingModule extends Module {
   RoutingModule({bool usePushState: true}) {
     bind(NgRoutingUsePushState);
@@ -162,10 +167,10 @@ class RoutingModule extends Module {
 
 /**
  * Allows configuration of [Router.useFragment]. By default [usePushState] is
- * true, so the router will listen to [Window.onPopState] and route URLs like
+ * true, so the router will listen to `Window.onPopState` and route URLs like
  * "http://host:port/foo/bar?baz=qux". Both the path and query parts of the URL
  * are used by the router. If [usePushState] is false, router will listen to
- * [Window.onHashChange] and route URLs like
+ * `Window.onHashChange` and route URLs like
  * "http://host:port/path#/foo/bar?baz=qux". Everything after hash (#) is used
  * by the router.
  */
diff --git a/lib/routing/ng_view.dart b/lib/routing/ng_view.dart
index ff364fdc0..80f2deb4f 100644
--- a/lib/routing/ng_view.dart
+++ b/lib/routing/ng_view.dart
@@ -1,7 +1,7 @@
 part of angular.routing;
 
 /**
- * A directive that works with the [Router] and loads the template associated with the current
+ * A directive that works with the `Router` and loads the template associated with the current
  * route.
  *
  *     <ng-view></ng-view>
@@ -198,7 +198,7 @@ class NgView implements DetachAware, RouteProvider {
  */
 abstract class RouteProvider {
   /**
-   * Returns [Route] for current view.
+   * Returns `Route` for current view.
    */
   Route get route;
 
diff --git a/lib/routing/routing.dart b/lib/routing/routing.dart
index 116d20c2c..94f4b48bc 100644
--- a/lib/routing/routing.dart
+++ b/lib/routing/routing.dart
@@ -71,6 +71,14 @@ class RouteViewFactory {
   }
 }
 
+/**
+ * A factory function for [NgRouteCfg]. Most of the parameters are passes directly
+ * to route_hierachical API for route configuration (`Route.addRoute`).
+ *
+ * * [view] - a URL of the template to load into ng-view when route is entered.
+ * * [viewHtml] - HTML of the template to load into ng-view when route is entered.
+ * * [modules] - a list of di modules to load for the route/ng-view.
+ */
 NgRouteCfg ngRoute({String path, String view, String viewHtml,
     Map<String, NgRouteCfg> mount, modules(), bool defaultRoute: false,
     RoutePreEnterEventHandler preEnter, RouteEnterEventHandler enter,
@@ -79,7 +87,10 @@ NgRouteCfg ngRoute({String path, String view, String viewHtml,
         new NgRouteCfg(path: path, view: view, viewHtml: viewHtml, mount: mount,
             modules: modules, defaultRoute: defaultRoute, preEnter: preEnter, preLeave: preLeave,
             enter: enter, leave: leave, dontLeaveOnParamChanges: dontLeaveOnParamChanges);
-
+/**
+ * Object containing route configuration parameters. Typically this class
+ * is not used directly, but rather constructed via [ngRoute] factory function.
+ */
 class NgRouteCfg {
   final String path;
   final String view;