Generate types from JSDoc

[mikaelkaron]

Instead of maintaining separate @types/* it would be nice to have types generated and shipped with the package.

This PR adds support for generating *.d.ts from JSDoc style comments.

[mikaelkaron]

@fergiemcdowall Is this something you'd be interested in?

At the moment I'm extracting what I can from the docs and code comments where I can find them, but long-term this should be a lot more maintainable (and possibly testable) than a separate @types/* package.

[fergiemcdowall]

Yes absolutely 👍👍 (I see that level now includes Typescript definitions)

[mikaelkaron]

For some reason I'm not able to output all the types to:

• one file in dist
• separate types dir

So for now I'm just using the default (that works) of outputting the *.d.ts file next to the source.

[fergiemcdowall]

I havent really been using Typescript lately- what is the best way to verify that the Types are correct? Say we get a PR that breaks a type- how do we run a test that picks that up?

[mikaelkaron]

I've completed a first round of types generated from JSDoc now and it would be awesome if someone can help me review that the types I've documented/generated are correct. Generated types are not as good as manually created types, for instance:

• Generics are not that easy to get right
• Not able to generate interface - it's always a type
• Parameter documentation is not extracted to the generated type
• You are supposed to be able to generate types to a specific types folder and even a separate index.d.ts but I have not been able to do that yet.

It's possible that's due to me not understanding how to do that - if someone knows how to address the above please go for it ;)

I havent really been using Typescript lately- what is the best way to verify that the Types are correct? Say we get a PR that breaks a type- how do we run a test that picks that up?

I think the best we can do is to add tsd tests.