75
Vote

Generate XML Doc comments

description

Scenario:
  • Entity A uses TypeScript to generate a JavaScript library, and offers it in both TypeScript and JavaScript form.
  • Entity B chooses to consume the JavaScript version, but all the type information is lost, so there's no useful Intellisense in Visual Studio.
Solution: generate rudimentary XML Doc comments in the generated JS so that Intellisense can start to reason about the JS code and imply some rough type information.

comments

LukeH wrote Oct 2, 2012 at 8:23 PM

Yep - optionally generating XML (for VS tooling) and/or JSDoc (for broader JS tools pipelines) comments based on TypeScript type information is a planned area of investment.

gmosx wrote Oct 10, 2012 at 8:27 AM

Please also add support for emitting JSDoc comments for use by closure compiler and tools.

markrendle wrote Nov 19, 2012 at 11:28 AM

Seems like focusing on emitting JSDoc (and making VS2012 consume JSDoc metadata too) would be the most efficient investment of time, since that would give TypeScript the best support for other tooling (IDEs, minifiers, etc.) and VS2012 the best support for working with a wide range of JavaScript libraries.

jonturner wrote Mar 7, 2013 at 9:59 PM

Agreed - there are scenarios where this would be very helpful, whether as part of a toolchain or as documentation that's output in the JS. I'm not sure if the feature will make the cut for 1.0, as we're largely focusing on extending the language so that it can work with existing JS more smoothly in the 1.0 timeframe. After 1.0, this sounds like a natural thing to look into as a possibility because we already have the type information and we already support JSDoc consumption.

basarat wrote Apr 28, 2013 at 11:39 PM

I am sure you guys know, but JSDoc would be much more valuable for usage by other tools as well. I really do not have any use for XML comments if they are VS specific. VS can understand typescript anyways.

nodirt wrote May 16, 2013 at 6:36 PM

Any estimation on when this can be implemented?

We've built our own metadata generation tool that converts AST and JSDoc from a .ts file to a .ts.xml file with information about classes, interfaces, methods, parameters, fields, events, as well as some non-standard stuff like jQuery UI Widgets. The tool uses TypeScript parser to parse source files. The metadata files are used to generate HTML documentation.

We were going to fork TypeScript compiler to include metadata generation as a part of compilation, but now it seems that it does not worth to do it since you are going to do it anyway.

Do you still not accept pull requests?

nodirt wrote May 16, 2013 at 7:49 PM

Could you please tell if you think towards making the generated XML format look like the one generated by C# compiler, or it may look quite differently?

billyzkid wrote Jun 28, 2013 at 6:31 PM

+1 for jsDoc instead of xmlDoc format. but we need better tools for auto-generating API documentation than what's currently out there. jsDoc3 isn't cutting it.

wizzard0 wrote Aug 11, 2013 at 2:17 PM

+1 for both vsdoc/jsdoc

WayneBloss wrote Sep 15, 2013 at 10:15 PM

+1 for both vsdoc and jsdoc please.

Bitterman wrote Nov 20, 2013 at 9:44 PM

Both XML and jsdoc would be nice. I guess jsdoc is more important, but I'm more used to XML (in C#), so...