docs(module): improve the installation instructions for optional modules

Currently, the documentation does a bad job of explaining the distinction between the services that it provides,
and the module itself. Furthermore, the instructions for using optional modules are inconsistent or missing.
This commit addresses the problem by ading a new `{@installModule foo}` annotation to the docs generator that
inlines the appropriate instructions based on the name of the module.

3 files changed, 19 insertions, 15 deletions

diff --git a/src/ngRoute/directive/ngView.js b/src/ngRoute/directive/ngView.js
index 6a1f2012..3b97367c 100644
--- a/src/ngRoute/directive/ngView.js
+++ b/src/ngRoute/directive/ngView.js
@@ -14,6 +14,8 @@ ngRouteModule.directive('ngView', ngViewFactory);
  * Every time the current route changes, the included view changes with it according to the
  * configuration of the `$route` service.
  *
+ * Requires the {@link ngRoute `ngRoute`} module to be installed.
+ *
  * @animations
  * enter - animation is used to bring new content into the browser.
  * leave - animation is used to animate existing content away.
diff --git a/src/ngRoute/route.js b/src/ngRoute/route.js
index 117e7abf..c487d6f1 100644
--- a/src/ngRoute/route.js
+++ b/src/ngRoute/route.js
@@ -5,17 +5,11 @@
  * @name ngRoute
  * @description
  *
- * ngRoute
- * =========
+ * # ngRoute
  *
- * The ngRoute module provides routing and deeplinking services and directives for angular apps.
+ * The `ngRoute` module provides routing and deeplinking services and directives for angular apps.
  *
- * To make use of routing with AngularJS, the `angular-route.js` JavaScript file must be included into your application
- * and the `ngRoute` module must be included as a dependency.
- *
- * <pre>
- * angular.module('App', ['ngRoute']);
- * </pre>
+ * {@installModule route}
  *
  */
 
@@ -30,6 +24,8 @@ var ngRouteModule = angular.module('ngRoute', ['ng']).
  * @description
  *
  * Used for configuring routes. See {@link ngRoute.$route $route} for an example.
+ *
+ * Requires the {@link ngRoute `ngRoute`} module to be installed.
  */
 function $RouteProvider(){
   var routes = {};
@@ -231,13 +227,15 @@ function $RouteProvider(){
      * @property {Array.<Object>} routes Array of all configured routes.
      *
      * @description
-     * Is used for deep-linking URLs to controllers and views (HTML partials).
+     * `$route` is used for deep-linking URLs to controllers and views (HTML partials).
      * It watches `$location.url()` and tries to map the path to an existing route definition.
      *
+     * Requires the {@link ngRoute `ngRoute`} module to be installed.
+     *
      * You can define routes through {@link ngRoute.$routeProvider $routeProvider}'s API.
      *
-     * The `$route` service is typically used in conjunction with {@link ngRoute.directive:ngView ngView}
-     * directive and the {@link ngRoute.$routeParams $routeParams} service.
+     * The `$route` service is typically used in conjunction with the {@link ngRoute.directive:ngView `ngView`}
+     * directive and the {@link ngRoute.$routeParams `$routeParams`} service.
      *
      * @example
        This example shows how changing the URL hash causes the `$route` to match a route against the
diff --git a/src/ngRoute/routeParams.js b/src/ngRoute/routeParams.js
index 0007e833..4d306e89 100644
--- a/src/ngRoute/routeParams.js
+++ b/src/ngRoute/routeParams.js
@@ -9,9 +9,13 @@ ngRouteModule.provider('$routeParams', $RouteParamsProvider);
  * @requires $route
  *
  * @description
- * Current set of route parameters. The route parameters are a combination of the
- * {@link ng.$location $location} `search()`, and `path()`. The `path` parameters
- * are extracted when the {@link ngRoute.$route $route} path is matched.
+ * The `$routeParams` service allows you to retrieve the current set of route parameters.
+ *
+ * Requires the {@link ngRoute `ngRoute`} module to be installed.
+ *
+ * The route parameters are a combination of {@link ng.$location `$location`}'s
+ * {@link ng.$location#search `search()`} and {@link ng.$location#path `path()`}.
+ * The `path` parameters are extracted when the {@link ngRoute.$route `$route`} path is matched.
  *
  * In case of parameter name collision, `path` params take precedence over `search` params.
  *