JSDoc @property and @memberOf tags

[donmccurdy]

Is your feature request related to a problem? Please describe.

The TypeScript compiler supports a subset of JSDoc, not including @property and @memberOf tags. The limitation is currently tracked in microsoft/TypeScript#7237 and a few other tickets.

I'm interested in generating .d.ts type definitions for JavaScript source files containing JSDoc type annotations, like this example:

/**
 * @property {number} id
 */
class Value {
  constructor() {
    Object.defineProperty( this, 'id', { value: _nextId ++ } );
  }
}

Currently both TypeScript and TS Morph ignore the @property annotation above, meaning that part of my exported API is untyped and undocumented.

Describe the solution you'd like

I'd love for TypeScript or TS Morph (or both!) to be able to parse these JSDoc tags. In the case of TS Morph, I'm unsure whether it's reasonable to do full type inference based on the JSDoc, or only to parse the JSDoc tag as something typed rather than "JSDocUnknownTag".

Is this something you'd be interested in, and would PRs be welcome? Thanks!

Describe alternatives you've considered

N/A

[kungfooman]

This would come in handy for ES5 style classes aswell:

ts-ast-viewer.com

[dsherret]

This is something that TypeScript would have to implement. ts-morph doesn't do any jsdoc parsing beyond what typescript supports.

[kungfooman]

ts-morph: TypeScript Compiler API wrapper for static analysis and programmatic code changes.

This is pretty much a programmatic code change, isn't it?

The JSDoc tag is parsed already, all it needs to generate a types.d.ts from the AST is a little extra parsing (which we can also use TS for):

@donmccurdy I'm not sure why you even need ts-morph, the TS API is good enough?

[donmccurdy]

I'm not sure why you even need ts-morph, the TS API is good enough?

It's not obvious to me how I'd transfer that type information from the AST to valid type definitions... more than a little parsing surely? The TS API sees the JSDoc perhaps, but doesn't infer type information from it ... I could imagine using TS Morph to "port" JavaScript+JSDoc to valid TypeScript, then compile type definitions from that, but it does seem like it would get complex to handle full type expressions in the JSDOC.

In any case – if everything depends on TypeScript implementing support for the JSDoc tags, feel free to close the issue here. Thanks!

[kungfooman]

@donmccurdy Well, yes, TypeScript itself is not a big help here. I actually did the same some time ago with another purpose in mind, but I used Babel.js... I parse every JSDoc comment myself, filter/merge the type information and this type information you can then parse with TypeScript for highest compatibility (or in the case of generating a .d.ts, you don't even need to parse it any longer, since it already is TS).

I prefer Babel's AST, since TypeScript just got a bunch of ID's in every node, which is unreadable to quickly skim through.