feat(typings): allow declaration of reference paths

Without this feature, each bundle would have to create its own typings
template to include references to dependent typings. Now, the references
can be declared in JS, along with other meta information about the 
bundle typings.


Closes #3540

docs/typescript-definition-package/index.js

@@ -42,20 +42,23 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage,
     'angular2/router.ts'
   ];
   readTypeScriptModules.basePath = path.resolve(path.resolve(__dirname, '../../modules'));
-  
+
   createTypeDefinitionFile.typeDefinitions = [
       {
         id: 'angular2/angular2',
+        references: ['../es6-promise/es6-promise.d.ts', '../rx/rx.d.ts'],
         modules: {
           'angular2/angular2': 'angular2/angular2',
         }
       },
       {
         id: 'angular2/router',
+        //Right now the typings live in the same directory, but eventually will not. See #3458
+        references: ['../angular2/angular2.d.ts'],
         modules: {
           'angular2/router': 'angular2/router'
         }
-      }    
+      }
   ];
 })
 

docs/typescript-definition-package/processors/createTypeDefinitionFile.js

@@ -33,7 +33,7 @@ module.exports = function createTypeDefinitionFile(log) {
           // 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 };
+            moduleDocs[id] = { id: alias, doc: null, references: def.references };
           })
         };
       });
@@ -63,7 +63,7 @@ module.exports = function createTypeDefinitionFile(log) {
               // Convert this class to an interface with no constructor
               exportDoc.docType = 'interface';
               exportDoc.constructorDoc = null;
-              
+
               if (exportDoc.heritage) {
                 // convert the heritage since interfaces use `extends` not `implements`
                 exportDoc.heritage = exportDoc.heritage.replace('implements', 'extends');

docs/typescript-definition-package/templates/angular2/angular2.d.ts.template.html

@@ -1,10 +1,5 @@
 {% 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> {}

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

@@ -28,6 +28,14 @@
 // Please do not create manual edits or send pull requests
 // modifying this file.
 // ***********************************************************
+{% for alias, module in doc.moduleDocs %}
+{%- if module.references.length %}
+// Angular depends transitively on these libraries.
+// If you don't have them installed you can install them using TSD
+// https://github.com/DefinitelyTyped/tsd
+{%- endif %}
+{% for reference in module.references %}
+///<reference path="{$ reference $}"/>{% endfor %}{% endfor %}
 {% block staticDeclarations %}{% endblock %}
 {% for alias, module in doc.moduleDocs %}
 {$ commentBlock(module.doc, 1) $}