chore(doc-gen): generate router typings file

Closes angular#2659

Author: petebacondarwin

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'],
+ $validate: {
+ dtsPath: { presence: true },
+ dtsExtension: { presence: true },
+ typeDefinitions: { presence: true }
+ },
+ dtsPath: 'typings',
+ dtsExtension: '.d.ts',
+ typeDefinitions: [
+ {
+ 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
+ 'angular2/angular2': 'angular2/angular2.api',
+ }
+ },
+ {
+ id: 'angular2/router',
+ modules: {
+ 'angular2/router': 'angular2/router'
+ }
+ }
+ ],
  $process: function(docs) {
- var typeDefDoc = {
- id: 'type-definition',
- aliases: ['type-definition'],
- path: 'type-definition',
- outputPath: 'typings/angular2/angular2.d.ts',
- modules: []
- };
+ 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) {
- // 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') {
- doc.id = 'angular2/angular2';
- typeDefDoc.modules.push(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.
 // ***********************************************************
-
-// 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;
- }
-}
-{% for module in doc.modules %}
-{$ commentBlock(module, 1) $}
+{% block staticDeclarations %}{% endblock %}
+{% for alias, module in doc.moduleDocs %}
+{$ commentBlock(module.doc, 1) $}
 declare module "{$ module.id $}" {
 
- {%- for export in module.exports -%}
+ {%- for export in module.doc.exports -%}
  {%- if export.content -%}
  {$ commentBlock(export, 3) $}
  {%- endif %}