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.

14 files changed, 117 insertions, 73 deletions

diff --git a/docs/content/api/ng.ngdoc b/docs/content/api/ng.ngdoc
index 95295e69..5c2f9517 100644
--- a/docs/content/api/ng.ngdoc
+++ b/docs/content/api/ng.ngdoc
@@ -2,4 +2,4 @@
 @name ng
 @description
 
-The `ng` is an angular module which contains all of the core angular services.
+`ng` is the name of the {@link guide/module angular module} that contains all of the core angular services.
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index e752b447..a9f470cc 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -276,6 +276,9 @@ Doc.prototype = {
         replace(/{@type\s+(\S+)(?:\s+(\S+))?}/g, function(_, type, url) {
           url = url || '#';
           return '<a href="' + url + '" class="' + self.prepare_type_hint_class_name(type) + '">' + type + '</a>';
+        }).
+        replace(/{@installModule\s+(\S+)?}/g, function(_, module) {
+          return explainModuleInstallation(module);
         });
     });
     text = parts.join('');
@@ -450,7 +453,6 @@ Doc.prototype = {
       dom.text(' Improve this doc');
     });
     dom.h(title(this), function() {
-
       notice('deprecated', 'Deprecated API', self.deprecated);
       if (self.ngdoc === 'error') {
         minerrMsg = lookupMinerrMsg(self);
@@ -1169,3 +1171,28 @@ function dashCase(name){
     return (pos ? '-' : '') + letter.toLowerCase();
   });
 }
+//////////////////////////////////////////////////////////
+
+function explainModuleInstallation(moduleName){
+  var ngMod = ngModule(moduleName),
+    modulePackage = 'angular-' + moduleName,
+    modulePackageFile = modulePackage + '.js';
+
+  return '<h1>Installation</h1>' +
+    '<p>First include <code>' + modulePackageFile +'</code> in your HTML:</p><pre><code>' +
+    '    &lt;script src=&quot;angular.js&quot;&gt;\n' +
+    '    &lt;script src=&quot;' + modulePackageFile + '&quot;&gt;</pre></code>' +
+
+    '<p>You can also find this file on the [Google CDN](https://developers.google.com/speed/libraries/devguide#angularjs), ' +
+    '<a href="http://bower.io/">Bower</a> (as <code>' + modulePackage + '</code>), ' +
+    'and on <a href="http://code.angularjs.org/">code.angularjs.org</a>.</p>' +
+
+    '<p>Then load the module in your application by adding it as a dependant module:</p><pre><code>' +
+    '    angular.module(\'app\', [\'' + ngMod + '\']);</pre></code>' +
+
+    '<p>With that you\'re ready to get started!</p>';
+}
+
+function ngModule(moduleName) {
+  return 'ng' + moduleName[0].toUpperCase() + moduleName.substr(1);
+}
diff --git a/src/ngAnimate/animate.js b/src/ngAnimate/animate.js
index c43401ec..4207470b 100644
--- a/src/ngAnimate/animate.js
+++ b/src/ngAnimate/animate.js
@@ -3,20 +3,15 @@
  * @name ngAnimate
  * @description
  *
- * ngAnimate
- * =========
+ * # ngAnimate
  *
- * The ngAnimate module is an optional module that comes packed with AngularJS that can be included within an AngularJS
- * application to provide support for CSS and JavaScript animation hooks.
+ * `ngAnimate` is an optional module that provides CSS and JavaScript animation hooks.
  *
- * To make use of animations with AngularJS, the `angular-animate.js` JavaScript file must be included into your application
- * and the `ngAnimate` module must be included as a dependency.
+ * {@installModule animate}
  *
- * <pre>
- * angular.module('App', ['ngAnimate']);
- * </pre>
+ * # Usage
  *
- * Then, to see animations in action, all that is required is to define the appropriate CSS classes
+ * To see animations in action, all that is required is to define the appropriate CSS classes
  * or to register a JavaScript animation via the $animation service. The directives that support animation automatically are:
  * `ngRepeat`, `ngInclude`, `ngSwitch`, `ngShow`, `ngHide` and `ngView`. Custom directives can take advantage of animation
  * by using the `$animate` service.
@@ -46,7 +41,7 @@
  *   -o-transition:0.5s linear all;
  *   transition:0.5s linear all;
  * }
- * 
+ *
  * .slide.ng-enter { }        /&#42; starting animations for enter &#42;/
  * .slide.ng-enter-active { } /&#42; terminal animations for enter &#42;/
  * .slide.ng-leave { }        /&#42; starting animations for leave &#42;/
@@ -190,11 +185,13 @@ angular.module('ngAnimate', ['ng'])
    * @name ngAnimate.$animateProvider
    * @description
    *
-   * The $AnimationProvider provider allows developers to register and access custom JavaScript animations directly inside
+   * The `$AnimationProvider` allows developers to register and access custom JavaScript animations directly inside
    * of a module. When an animation is triggered, the $animate service will query the $animation function to find any
    * animations that match the provided name value.
    *
-   * Please visit the {@link ngAnimate ngAnimate} module overview page learn more about how to use animations in your application.
+   * Requires the {@link ngAnimate `ngAnimate`} module to be installed.
+   *
+   * Please visit the {@link ngAnimate `ngAnimate`} module overview page learn more about how to use animations in your application.
    *
    */
   .config(['$provide', '$animateProvider', function($provide, $animateProvider) {
@@ -206,7 +203,7 @@ angular.module('ngAnimate', ['ng'])
     var rootAnimateState = {running:true};
     $provide.decorator('$animate', ['$delegate', '$injector', '$sniffer', '$rootElement', '$timeout',
                             function($delegate,   $injector,   $sniffer,   $rootElement,   $timeout) {
-        
+
       $rootElement.data(NG_ANIMATE_STATE, rootAnimateState);
 
       function lookup(name) {
@@ -248,7 +245,9 @@ angular.module('ngAnimate', ['ng'])
        * The `$animate` service is used behind the scenes with pre-existing directives and animation with these directives
        * will work out of the box without any extra configuration.
        *
-       * Please visit the {@link ngAnimate ngAnimate} module overview page learn more about how to use animations in your application.
+       * Requires the {@link ngAnimate `ngAnimate`} module to be installed.
+       *
+       * Please visit the {@link ngAnimate `ngAnimate`} module overview page learn more about how to use animations in your application.
        *
        */
       return {
diff --git a/src/ngCookies/cookies.js b/src/ngCookies/cookies.js
index 7309b558..2f9dd333 100644
--- a/src/ngCookies/cookies.js
+++ b/src/ngCookies/cookies.js
@@ -3,6 +3,17 @@
 /**
  * @ngdoc overview
  * @name ngCookies
+ * @description
+ *
+ * # ngCookies
+ *
+ * Provides the {@link ngCookies.$cookies `$cookies`} and
+ * {@link ngCookies.$cookieStore `$cookieStore`} services.
+ *
+ * {@installModule cookies}
+ *
+ * See {@link ngCookies.$cookies `$cookies`} and
+ * {@link ngCookies.$cookieStore `$cookieStore`} for usage.
  */
 
 
@@ -18,16 +29,7 @@ angular.module('ngCookies', ['ng']).
    * Only a simple Object is exposed and by adding or removing properties to/from
    * this object, new cookies are created/deleted at the end of current $eval.
    *
-   * # Installation
-   * To use $cookies make sure you have included the `angular-cookies.js` that comes in Angular
-   * package. You can also find this file on Google CDN, bower as well as at
-   * {@link http://code.angularjs.org/ code.angularjs.org}.
-   *
-   * Finally load the module in your application:
-   *
-   *        angular.module('app', ['ngCookies']);
-   *
-   * and you are ready to get started!
+   * Requires the {@link ngCookies `ngCookies`} module to be installed.
    *
    * @example
    <doc:example>
@@ -133,6 +135,9 @@ angular.module('ngCookies', ['ng']).
    * Provides a key-value (string-object) storage, that is backed by session cookies.
    * Objects put or retrieved from this storage are automatically serialized or
    * deserialized by angular's toJson/fromJson.
+   *
+   * Requires the {@link ngCookies `ngCookies`} module to be installed.
+   *
    * @example
    */
    factory('$cookieStore', ['$cookies', function($cookies) {
diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js
index 719fea5d..2434ad68 100644
--- a/src/ngResource/resource.js
+++ b/src/ngResource/resource.js
@@ -6,6 +6,16 @@ var $resourceMinErr = angular.$$minErr('$resource');
  * @ngdoc overview
  * @name ngResource
  * @description
+ *
+ * # ngResource
+ *
+ * `ngResource` is the name of the optional Angular module that adds support for interacting with
+ * [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer) server-side data sources.
+ * `ngReource` provides the {@link ngResource.$resource `$resource`} serivce.
+ *
+ * {@installModule resource}
+ *
+ * See {@link ngResource.$resource `$resource`} for usage.
  */
 
 /**
@@ -20,16 +30,7 @@ var $resourceMinErr = angular.$$minErr('$resource');
  * The returned resource object has action methods which provide high-level behaviors without
  * the need to interact with the low level {@link ng.$http $http} service.
  *
- * # Installation
- * To use $resource make sure you have included the `angular-resource.js` that comes in Angular
- * package. You can also find this file on Google CDN, bower as well as at
- * {@link http://code.angularjs.org/ code.angularjs.org}.
- *
- * Finally load the module in your application:
- *
- *        angular.module('app', ['ngResource']);
- *
- * and you are ready to get started!
+ * Requires the {@link ngResource `ngResource`} module to be installed.
  *
  * @param {string} url A parametrized URL template with parameters prefixed by `:` as in
  *   `/user/:username`. If you are using a URL with a port number (e.g.
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.
  *
diff --git a/src/ngSanitize/filter/linky.js b/src/ngSanitize/filter/linky.js
index cc0f7aa6..282a6117 100644
--- a/src/ngSanitize/filter/linky.js
+++ b/src/ngSanitize/filter/linky.js
@@ -4,8 +4,10 @@
  * @function
  *
  * @description
- *   Finds links in text input and turns them into html links. Supports http/https/ftp/mailto and
- *   plain email address links.
+ * Finds links in text input and turns them into html links. Supports http/https/ftp/mailto and
+ * plain email address links.
+ *
+ * Requires the {@link ngSanitize `ngSanitize`} module to be installed.
  *
  * @param {string} text Input text.
  * @param {string} target Window (_blank|_self|_parent|_top) or named frame to open links in.
diff --git a/src/ngSanitize/sanitize.js b/src/ngSanitize/sanitize.js
index 8220b1f5..3d904ad1 100644
--- a/src/ngSanitize/sanitize.js
+++ b/src/ngSanitize/sanitize.js
@@ -6,25 +6,14 @@ var $sanitizeMinErr = angular.$$minErr('$sanitize');
  * @ngdoc overview
  * @name ngSanitize
  * @description
- * 
- * The `ngSanitize` module provides functionality to sanitize HTML.
- * 
- * # Installation
- * As a separate module, it must be loaded after Angular core is loaded; otherwise, an 'Uncaught Error:
- * No module: ngSanitize' runtime error will occur.
  *
- * <pre>
- *   <script src="angular.js"></script>
- *   <script src="angular-sanitize.js"></script>
- * </pre>
+ * # ngSanitize
+ *
+ * The `ngSanitize` module provides functionality to sanitize HTML.
  *
- * # Usage
- * To make sure the module is available to your application, declare it as a dependency of you application
- * module.
+ * {@installModule sanitize}
  *
- * <pre>
- *   angular.module('app', ['ngSanitize']);
- * </pre>
+ * See {@link ngSanitize.$sanitize `$sanitize`} for usage.
  */
 
 /*
diff --git a/src/ngTouch/directive/ngClick.js b/src/ngTouch/directive/ngClick.js
index f1d8ccaa..d6e404ca 100644
--- a/src/ngTouch/directive/ngClick.js
+++ b/src/ngTouch/directive/ngClick.js
@@ -10,6 +10,8 @@
  * the click event. This version handles them immediately, and then prevents the
  * following click event from propagating.
  *
+ * Requires the {@link ngTouch `ngTouch`} module to be installed.
+ *
  * This directive can fall back to using an ordinary click event, and so works on desktop
  * browsers as well as mobile.
  *
diff --git a/src/ngTouch/directive/ngSwipe.js b/src/ngTouch/directive/ngSwipe.js
index e754113c..a5911f9a 100644
--- a/src/ngTouch/directive/ngSwipe.js
+++ b/src/ngTouch/directive/ngSwipe.js
@@ -9,6 +9,8 @@
  * A leftward swipe is a quick, right-to-left slide of the finger.
  * Though ngSwipeLeft is designed for touch-based devices, it will work with a mouse click and drag too.
  *
+ * Requires the {@link ngTouch `ngTouch`} module to be installed.
+ *
  * @element ANY
  * @param {expression} ngSwipeLeft {@link guide/expression Expression} to evaluate
  * upon left swipe. (Event object is available as `$event`)
@@ -36,6 +38,8 @@
  * A rightward swipe is a quick, left-to-right slide of the finger.
  * Though ngSwipeRight is designed for touch-based devices, it will work with a mouse click and drag too.
  *
+ * Requires the {@link ngTouch `ngTouch`} module to be installed.
+ *
  * @element ANY
  * @param {expression} ngSwipeRight {@link guide/expression Expression} to evaluate
  * upon right swipe. (Event object is available as `$event`)
diff --git a/src/ngTouch/swipe.js b/src/ngTouch/swipe.js
index 655043f8..0ee4218e 100644
--- a/src/ngTouch/swipe.js
+++ b/src/ngTouch/swipe.js
@@ -8,7 +8,9 @@
      * The `$swipe` service is a service that abstracts the messier details of hold-and-drag swipe
      * behavior, to make implementing swipe-related directives more convenient.
      *
-     * It is used by the `ngSwipeLeft` and `ngSwipeRight` directives in `ngTouch`, and by
+     * Requires the {@link ngTouch `ngTouch`} module to be installed.
+     *
+     * `$swipe` is used by the `ngSwipeLeft` and `ngSwipeRight` directives in `ngTouch`, and by
      * `ngCarousel` in a separate component.
      *
      * # Usage
diff --git a/src/ngTouch/touch.js b/src/ngTouch/touch.js
index 844350aa..0e9229b2 100644
--- a/src/ngTouch/touch.js
+++ b/src/ngTouch/touch.js
@@ -4,8 +4,17 @@
  * @ngdoc overview
  * @name ngTouch
  * @description
- * Touch events and other mobile helpers.
- * Based on jQuery Mobile touch event handling (jquerymobile.com)
+ *
+ * # ngTouch
+ *
+ * `ngTouch` is the name of the optional Angular module that provides touch events and other
+ * helpers for touch-enabled devices.
+ * The implementation is based on jQuery Mobile touch event handling
+ * ([jquerymobile.com](http://jquerymobile.com/))
+ *
+ * {@installModule touch}
+ *
+ * See {@link ngTouch.$swipe `$swipe`} for usage.
  */
 
 // define ngTouch module