You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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 a
symbol.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 thesourceFile.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 theexternalModuleIndicator
may become an array. I will check that out in the coming weeks. Anyway, parameters will have to change fromstring[]
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.
The text was updated successfully, but these errors were encountered: