From 561b78a5b39a595c35d9e559f2855d9cbfad3f3c Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Thu, 2 Jul 2015 08:13:54 +0100 Subject: [PATCH] chore(doc-gen): generate router typings file Closes #2659 --- .../processors/createTypeDefinitionFile.js | 82 +++++++++++++++---- .../angular2/angular2.d.ts.template.html | 25 ++++++ .../templates/type-definition.template.html | 31 +------ 3 files changed, 95 insertions(+), 43 deletions(-) create mode 100644 docs/dgeni-package/templates/angular2/angular2.d.ts.template.html diff --git a/docs/dgeni-package/processors/createTypeDefinitionFile.js b/docs/dgeni-package/processors/createTypeDefinitionFile.js index 142f94011b..f0a90efb56 100644 --- a/docs/dgeni-package/processors/createTypeDefinitionFile.js +++ b/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) { - var typeDefDoc = { - id: 'type-definition', - aliases: ['type-definition'], - path: 'type-definition', - outputPath: 'typings/angular2/angular2.d.ts', - modules: [] - }; - _.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); + $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 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 }; + }) + }; }); - docs.push(typeDefDoc); + + // 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; + } + }); + }); + + _.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); } }; }; diff --git a/docs/dgeni-package/templates/angular2/angular2.d.ts.template.html b/docs/dgeni-package/templates/angular2/angular2.d.ts.template.html new file mode 100644 index 0000000000..4be251c555 --- /dev/null +++ b/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 +/// +/// + +interface List extends Array {} +interface Map {} +interface StringMap extends Map {} +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 %} \ No newline at end of file diff --git a/docs/dgeni-package/templates/type-definition.template.html b/docs/dgeni-package/templates/type-definition.template.html index 80698aca3b..afa928315e 100644 --- a/docs/dgeni-package/templates/type-definition.template.html +++ b/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 @@ -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 -/// -/// - -interface List extends Array {} -interface Map {} -interface StringMap extends Map {} -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 %}