Experiment: Create `.d.ts` files from JSDOc

[mroderick]

In order to better support the TypeScript community and have excellent API documentation, we would like to have great JSDoc comments for this library.

From the JSDoc comments we can extract .d.ts files, which will improve the experience of TypeScript users.

See sinonjs/fake-timers#345

---

However, we are using a construction that is yet unsupported by TypeScript: microsoft/TypeScript#33207

Basically, tsc doesn't understand this construction and doesn't support JSDoc's @interface annotation

/** @interface */
  function Encoder() {}
  Encoder.prototype = {
    handler: function(stream, code_point) {}
  };

A solution could be spread across several pull requests:

• Copy all the documentation from [nise] - Types definition for nise package (https://github.com/sinonjs/nise). DefinitelyTyped/DefinitelyTyped#30407 into this project as JSDoc comments
• Refactor the code to use expressions that can be documented with JSDoc and also understood by tsc
• Use tsc to generate .d.ts files

[HarelM]

Any update on this?
the typing there are better than the types in sinon as I see the lastRequst that is not documented in sinon typings.
But I don't see the aborted property for the FakeXMLHttpRequest interface.
Maintaining this in two repositories is not great.
It would be extremely cool to have the definitions file here and allow PR to this repo.
DefinitelyTyped repo is too big and I don't think can handle all the issues it has...

[fatso83]

@HarelM Hi, Harel. We had a decent attempt at doing this in the other Sinon projects, and as you can read from sinonjs/fake-timers#386 we decided to scrap the efforts. The test of using JSDoc to generate the typings did not live up to expectations, as JSDoc is not powerful enough to express the rich types that TypeScript allows for. At the same time, none of the current maintainers are interested in spending time supporting TypeScript (or PureScript or CoffeScript or any other transpiled language, for that matter), using our time on the core javascript matters.

I see the downside of keeping the typings in another repo, but there is no other way in the foreseeable future.

[HarelM]

Thanks for the info!
Is it possible to allow the community (or simply myself) to maintain this?
I don't mind maintaining a single typescript file in this repository assuming you tag me for all issues related to it.
Since changing the file is relatively easy and has minimal effect on this library from my experience people usually just send a PR to fix issues, the overhead of maintaining this is not big, again in my experience.
If this is something you guys might be interested let me know and I'll submit a PR to include the typescript file and the relevant changes to the package.json file.
I'm not talking about jsdocs here, just the typescript typings...
For reference, I've submitted a few PR for adding typings to all the libraries maplibre-gl that had missing or incorrect typings:
mapbox/vector-tile-js#78
mapbox/unitbezier#3
mapbox/tiny-sdf#39
mapbox/mapbox-gl-supported#40

These PRs are intended to solve these issues:
maplibre/maplibre-gl-js#554
maplibre/maplibre-gl-js#526
Thanks!!