Enhanced parameter data

[SirDarquan]

In my last issue #177, I asked that the @param peer into the TypeScript parameters property to allow it to associate untyped parameter descriptions with the types discovered by TypeScript so we can type a little less. Now I'm asking further enhance the data TypeScript exposes so that we can have richer documentation. Unfortunately, what I'm asking for would be a breaking change since the format of the parameter array would change.

The purpose

There are two pieces of data I'm interested in seeing exposed: If the type is external and the module it came from. As of now, we can know the type of a parameter but can't reliably link to the type declaration. This is because we don't know if the type is browser native, user-defined or externally defined. Doing a filter through the docs array will determine if it's user-defined but we still don't know about the others. Maybe linking to our own documentation is enough to explain how and why our code works. Then in a more broad description, explain what the foreign type is, why we need it and how we expect it to be used. Except that requires us to copy or paraphrase the original documentation (assuming there is some) and we barely want to document our own code.

Finding the extra data

I've found that Typescript can tell the difference between external and internal types but doesn't indicate when a type is 'native'. During the build up of a parameter, a sourceFile variable is created and initialized. All of the imported identifiers are listed in the following property: sourceFile.externalModuleIndicator.importClause.namedBindings.elements'. This is an array and each item contains asymbol.name' which is the external type. We can turn this into a simple array of just the symbol names for easy look up. In that same variable, there is also the sourceFile.externalModuleIndicator.moduleSpecifier.text which will give the module that list of identifiers came from. In my case, the type was NgZone so the text was "angular2/core" (haven't upgraded to the RC yet). I haven't done an import from multiple modules to see where it'll change to accommodate that yet but I suspect the externalModuleIndicator may become an array. I will check that out in the coming weeks. Anyway, parameters will have to change from string[] to more like {text:string, external?: boolean, moduleName?: string}[].

Pulling it all together

So now that we know when a parameter type is external and can search for internal types, when it's neither of those, it's probably native. At this point, we can make some type of type resolver system that can make links to the documentation for the type. For instance, if we're using localStorage ( a native type) it could create a link to https://developer.mozilla.org/docs/Web/API/Window/localStorage. Or if we're using Router, the link could be https://angular.io/docs/ts/latest/api/router/index/Router-class.html. This proposal sets the foundation for this type of system but it is a breaking change as I've mentioned before.