Generate type definitions from source files

[karfau]

We are currently maintaining the type defeinitons in index.d.ts by hand and relying heavily on many interfaces/types provided by adding /// <reference lib="dom" />.

Since the implementation differs in some significant ways, we need to ideally get rid of the reference.

It would be way better to generate them from our source files, so they stay in sync.

I already did multiple attempts on this, but never succeeded:

• Using jsdoc and tsd-jsdoc when running against lib/index.js doesn't give any output, when running against the other modules, many properties are put into the global scope. It looks like we would need to add way more tags for JSDoc to properly know the "hirarchy" of things, like modules, prototype members, etc.
• Using tpescript directly was also a rabbit whole without satisfying results, since it is not aware of our class extension mechanism, it complains about needing to declare private methods that is can not resolve and I didn't find a way to add jsdoc comment to satisfy tsc. (The same applies when trying to use tsdoc since it relies on the typescript compiler.

Any ideas, relevant information or experience is welcome to bring this topic forward.

[boneskull]

I spent a few mins exploring this, and while I think it's possible, it will take a good deal of fudging to deal with _extends.

A problem is that there's no way to tell TS, using its jsdoc syntax, that a constructor function "extends" some other "class". Further, I don't think it's possible to use @implements on these, which would otherwise be a potential workaround.

As you mentioned, the @private thing is an issue, and I don't see any way around that, though IIRC @ignore will fully-suppress something from declaration output.

Not sure this is all really worth it, though it would be good to document the extensions to the dom types that this lib adds. That should be pretty straightforward; just create a new interface extending e.g., Node, call it XDNode (or w/e) and add the new props, then re-export these. Of course, renaming them would probably be a breaking change for type consumers.

[boneskull]

You could also probably find a fanboy to rewrite it all in typescript. 😜

[AnWeber]

I refactored/ rewritten the XML Serializer and added formatting capabilities to them as well. This automatically provides its types as described in this issue. Maybe this is helpful for this issue.

https://github.com/AnWeber/xmldom-format/