chore(doc-gen): generate router typings file

Closes #2659

docs/dgeni-package/processors/createTypeDefinitionFile.js

@@ -1,27 +1,77 @@
 var _ = require('lodash');
+var path = require('canonical-path');
 
-module.exports = function createTypeDefinitionFile() {
+module.exports = function createTypeDefinitionFile(log) {
 
   return {
     $runAfter: ['processing-docs'],
     $runBefore: ['docs-processed'],
-    $process: function(docs) {
+    $validate: {
-      var typeDefDoc = {
+      dtsPath: { presence: true },
-        id: 'type-definition',
+      dtsExtension: { presence: true },
-        aliases: ['type-definition'],
+      typeDefinitions: { presence: true }
-        path: 'type-definition',
+    },
-        outputPath: 'typings/angular2/angular2.d.ts',
+    dtsPath: 'typings',
-        modules: []
+    dtsExtension: '.d.ts',
-      };
+    typeDefinitions: [
-      _.forEach(docs, function(doc) {
+      {
+        id: 'angular2/angular2',
+        modules: {
           // The shape of the public API is determined by what is reexported into
           // angular2/angular2, with hacks layered into angular2.api.ts
-        if (doc.id === 'angular2/angular2.api') {
+          'angular2/angular2': 'angular2/angular2.api',
-          doc.id = 'angular2/angular2';
+        }
-          typeDefDoc.modules.push(doc);
+      },
+      {
+        id: 'angular2/router',
+        modules: {
+          'angular2/router': 'angular2/router'
+        }
+      }
+    ],
+    $process: function(docs) {
+      var dtsPath = this.dtsPath;
+      var dtsExtension = this.dtsExtension;
+
+      // For each type definition that we wish to create we define a dgeni "doc" for it
+      var typeDefDocs = _.map(this.typeDefinitions, function(def) {
+
+        var id = def.id + dtsExtension;
+        var docPath = path.join(dtsPath, id);
+
+        return {
+          docType: 'type-definition',
+          id: id,
+          aliases: [id],
+          path: docPath,
+          outputPath: docPath,
+          // A type definition may include a number of top level modules
+          // And those modules could be aliased (such as 'angular2/angular2.api' -> 'angular2/angular2')
+          moduleDocs: _.transform(def.modules, function(moduleDocs, id, alias) {
+            moduleDocs[id] = { id: alias, doc: null };
+          })
+        };
+      });
+
+      // Now add all the module docs to their corresponding type definition doc
+      _.forEach(docs, function(doc) {
+        _.forEach(typeDefDocs, function(typeDefDoc) {
+          if(typeDefDoc.moduleDocs[doc.id]) {
+            typeDefDoc.moduleDocs[doc.id].doc = doc;
           }
         });
-      docs.push(typeDefDoc);
+      });
+
+      _.forEach(typeDefDocs, function(doc) {
+        _.forEach(doc.moduleDocs, function(modDoc, alias) {
+          if (!modDoc.doc) {
+            log.error('createTypeDefinitionFile processor: no such module "' + alias + '" (Did you forget to add it to the modules to load?)');
+          }
+        });
+      });
+
+      // Add all the type definition docs to the docs collection so that dgeni can process them
+      return docs.concat(typeDefDocs);
     }
   };
 };

docs/dgeni-package/templates/angular2/angular2.d.ts.template.html

@@ -0,0 +1,25 @@
+{% extends '../type-definition.template.html' %}
+{% block staticDeclarations %}
+// Angular depends transitively on these libraries.
+// If you don't have them installed you can run
+// $ tsd query es6-promise rx rx-lite --action install --save
+///<reference path="../es6-promise/es6-promise.d.ts"/>
+///<reference path="../rx/rx.d.ts"/>
+
+interface List<T> extends Array<T> {}
+interface Map<K,V> {}
+interface StringMap<K,V> extends Map<K,V> {}
+interface Type {}
+
+declare module "angular2/angular2" {
+  type SetterFn = typeof Function;
+  type int = number;
+
+  // See https://github.com/Microsoft/TypeScript/issues/1168
+  class BaseException /* extends Error */ {
+    message: string;
+    stack: string;
+    toString(): string;
+  }
+}
+{% endblock %}

docs/dgeni-package/templates/type-definition.template.html

@@ -5,7 +5,6 @@
 {$ doc.content | trim | replace(r/^/gm, "* ") | indent(level, true) | replace(r/\n$/, "") $}
 {$ '*/' | indent(level, true) | replace(r/\n$/, "") $}{% endif -%}
 {%- endmacro -%}
-
 // Type definitions for Angular v{$ versionInfo.currentVersion.full | replace(r/\+/, "_") $}
 // Project: http://angular.io/
 // Definitions by: angular team <https://github.com/angular/>
@@ -16,34 +15,12 @@
 // Please do not create manual edits or send pull requests
 // modifying this file.
 // ***********************************************************
-
+{% block staticDeclarations %}{% endblock %}
-// Angular depends transitively on these libraries.
+{% for alias, module in doc.moduleDocs %}
-// If you don't have them installed you can run
+{$ commentBlock(module.doc, 1) $}
-// $ tsd query es6-promise rx rx-lite --action install --save
-///<reference path="../es6-promise/es6-promise.d.ts"/>
-///<reference path="../rx/rx.d.ts"/>
-
-interface List<T> extends Array<T> {}
-interface Map<K,V> {}
-interface StringMap<K,V> extends Map<K,V> {}
-interface Type {}
-
-declare module "angular2/angular2" {
-  type SetterFn = typeof Function;
-  type int = number;
-
-  // See https://github.com/Microsoft/TypeScript/issues/1168
-  class BaseException /* extends Error */ {
-    message: string;
-    stack: string;
-    toString(): string;
-  }
-}
-{% for module in doc.modules %}
-{$ commentBlock(module, 1) $}
 declare module "{$ module.id $}" {
 
-  {%- for export in module.exports -%}
+  {%- for export in module.doc.exports -%}
   {%- if export.content -%}
     {$ commentBlock(export, 3) $}
   {%- endif %}