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.

2 files changed, 29 insertions, 2 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);
+}