6

Closed

TypeScript and JSDoc not playing well together

description

Commenting TypeScript classes with JSDoc is tedious and un-maintainable. Perhaps this is an issue with JSDoc or the default JSDoc template, but I thought I would bring it to your attention.

Here is a detailed description of the issue:
https://github.com/jsdoc3/jsdoc/issues/272
Closed Feb 20, 2013 at 1:31 AM by RyanCavanaugh
Closing 'fixed' issue. If you see issues around codegen comment placement, can you open separate issues to keep things organized? Thanks!

comments

RyanCavanaugh wrote Nov 28, 2012 at 6:31 PM

Indeed, the interop story here isn't great. This is something we're looking at for future milestones.

billyzkid wrote Nov 28, 2012 at 6:35 PM

I'm not sure how TypeScript can fix it without parsing the JSDoc comments and moving things around in the generated JavaScript, which is why I originally posted the issue on the JSDoc repo. Thoughts?

billyzkid wrote Nov 30, 2012 at 1:03 PM

I'm not convinced the JSDoc team will accept responsibility for fixing this, even if they could. So far, my original issue report has been met with stone silence.

So maybe it's entirely up to the TypeScript team...

As I detailed in the original issue (https://github.com/jsdoc3/jsdoc/issues/272), the most painful part is that the comments must include explicit names for the namespace/class/members in order for the docs to be generated correctly, which is a maintenance nightmare. For example:

@namespace My.Namespace
@class My.Namespace.SomeClass
@constructor My.Namespace.SomeClass
@member My.Namespace.SomeClass#_someField
@method My.Namespace.SomeClass#_someMethod

Could the tsc compiler be modified to parse, validate, and augment comments as well? It could generate the necessary JSDoc tags/names for the JSDoc generator to work and even add additional tags that it detects are missing, e.g. @public, @private, @readonly, @type {string}, etc.

That would be sweet.

jonturner wrote Feb 6, 2013 at 9:41 PM

We've begun supporting a simple subset of JSDoc in TypeScript that is understood by the language service and by the Visual Studio plugin. Marking this as 'fixed'.

jesschadwick wrote Apr 11 at 6:52 PM

The 1.0 language spec makes a single reference to the term "JSDoc" and no reference to any commenting support. Can you please elaborate? Perhaps a link to the source that defines TypeScript's JSDoc support?

johnny_reilly wrote Apr 12 at 8:55 AM

Hi Jess

Not aware of any docs but for a good example of how they're used you could look a the Definitely Typed jQuery.d.ts:

https://github.com/borisyankov/DefinitelyTyped/blob/master/jquery/jquery.d.ts

balassy wrote Apr 25 at 9:22 PM

The supported subset of JSDoc is very convenient if you use Visual Studio and want better IntelliSense. Not much coding required, minimal redundacy, they play nicely together, thank you!

However, there is no other tool on this planet (at least not one I'm aware of) that understands this subset. There are tons of tools that can generate a full documentation from JSDoc, and I could find one which could work with TypeScript. Either because they understand only JS but not TS, but mostly becuase they miss the full JSDoc tags from the comment blocks. Currently our comments are locked into VS and their only purpose is to lightup IntelliSense.

Please reopen this issue. Thank you.
  • György