Suggestion: Generate doc comments in emitted JS

[RyanCavanaugh]

Support some level of automatically generating doc comments for non-TypeScript JavaScript consumers.

Need more details on what exactly people would like to see generated.

[jvilk]

Most importantly, for me: Propagate type information into existing JSDoc comments. This would allow me to use existing JSDoc documentation generators to produce nice looking HTML documentation for my TypeScript libraries without respecifying type signatures in JSDoc comments.

(Of course, constructing a mapping between TypeScript types and JSDoc types might end up being nontrivial, especially where interface types are concerned.)

[jmatthiesen]

Making sure I understand you correctly - you'd like to see the type information from TypeScript persisted into JSDoc comments in the generated .js files from your TypeScript, right? Can you give an example of a documentation generator you currently use?

[jvilk]

you'd like to see the type information from TypeScript persisted into JSDoc comments in the generated .js files from your TypeScript, right?

Correct.

Can you give an example of a documentation generator you currently use?

I am not using a documentation generator at the moment (because it would be infeasible/frustrating to maintain type information in two locations as the code evolves), but I would like to use something like JSDoc: http://usejsdoc.org/

[sebastian-lenz]

I've created a documentation generator that can directly parse *.ts files and that understands TypeScript elements like classes or types. Maybe you would like to check it out:
https://github.com/sebastian-lenz/typedoc

[jvilk]

Your tool looks really nice! I'll have to see how it holds up to my code.

I figure it would be more elegant to avoid needing to maintain a separate project if we could find a decent mapping from TypeScript types and JSDoc annotations, but maybe that is a rathole in-and-of-itself.

[fsoikin]

We have a similar tool, but with a bit broader scope. It uses a template engine to generate output, which makes it perfectly usable for generating docs. Granted, there is more work for you (have to write the templates), but then you can make the output nicely customized.

Check it out: http://github.com/erecruit/TsT

[herrernst]

As the issues on Codeplex are now closed, I'd like to link to the JSDoc request there: http://typescript.codeplex.com/workitem/1596
IMHO, JSDoc annotated output would not only be good for documentation generators but also for other tools.

[mixtur]

+1 to herrernst
It would be nice to have JSDoc in emitted code, not because it would be easier to read later, but because such code can be feed to Google Closure compiler.
Generating already optimized code is another alternative.
Sorry for bad English.

[electricessence]

+1

Yup, annotations for the google closure compiler are a must for me. Having to do it manually really limits the advantages of typing. If you get your manual declarations incorrect, it can lead to incorrectly optimized results.

As far as the "needs proposal" tag goes.. do this please :) -- https://developers.google.com/closure/compiler/docs/js-for-compiler

[mirhagk]

In addition to the JSDoc comments, it may be worth looking into also supporting the exports and externs for the Google Closure Compiler
https://developers.google.com/closure/compiler/docs/api-tutorial3

EDIT: Emitting export and externs for Google Closure is mentioned in #8

[zzo]

+1 for closure-style type comment annoataions