Type descriptions for documentation of JavaScript APIs

[SamWhited]

Feature Description

I'd like to request that type description files (.d.ts), like those used to document the internal JavaScript APIs (see eg. midi-controller-api.d.ts and engine-api.d.ts) also be included for the various JavaScript files in the res/controllers/ tree.

These can be automatically generated from the JavaScript files, or they can be hand written. Writing them by hand would of course require more work, and require keeping them up to date, so it may not be something the maintainers want to do. Having them be auto generated by tsc(1) or dts-gen(1) could be handled as a pre-commit hook, in CI, or similar and would be faster, but you'd lose some of their ability to document the JavaScript (ie. the "options" type that's passed to various constructors in midi-components-0.0.js would not have a list of acceptable options, instead it would just be an arbitrary object, any). However, even automatically generated bindings would be extremely helpful for documenting the API, and they could be improved over time with type comments (which are already available for some functions). It's possible there are ways to specify more specific object types later as well, but for a first pass just having something in the directory next to the corresponding JavaScript file would make things much easier to read/figure out when writing a controller for the first time, I think.

Thank you for your consideration, I'm loving using Mixxx so far!

[Swiftb0y]

Ideally, just configure your editor/language-server so it can pick those up automatically. There is little reason to generate .d.ts files if the source with all the details is fully accessible IMO...

[SamWhited]

A lot of editors and tooling will specifically look for .d.ts files to determine if types are correct, they can't do this from the JavaScript or type comments directly (at least, that's my understanding, I am certainly no JavaScript expert, and I'm sure some use the comments too). In my case I don't use an IDE, but found reading the .d.ts files for the various APIs much easier than having to scroll through the entire implementation to figure out what's going on and still not have the auto-generated types themselves (and the type checker I use wants a .d.ts file).

[Swiftb0y]

I agree that its easier to read a d.ts, but editors likely can do it by hand. The challenge is making them aware that those files are actually used (and the language-server being able to actually understand the file). Both is not super straight-forward right now because our mappings do a lot of unorthodox stuff that are not easy to convey to editors. That may change in the future though.

[SamWhited]

Some editors can, but like I said, some like .d.ts files instead or can at least get more accurate type information from them (ie. they pull the function signature as foo(a, b, c) from the javascript, but the arguments are unknown because they don't read type comments, but if they have a matching .d.ts file generated from the type comments they know that a: number, b: string, c: someCallback or whatever). Also not everyone uses IDEs or language servers (I just use Vim).

[Swiftb0y]

right. Well I don't personally see a huge amount of value of shipping extra files that just duplicate/summarize existing info. Even if those file are autogenerated, keeping those in sync requires adding yet another tool. Usually the corresponding wiki page is supposed to serve as the best and most complete documentation as it also carries some additional explanatory value over just plain function signatures... So if you're prefer reading .d.ts and there are tools that can easily autogenerate them, I would just recommend to run them for you on your setup for now.

[SamWhited]

Yah, I auto-generated some for now, but it was a pain to setup. If they just already exist alongside the javascript files they would have just been picked up automatically. My last pitch is that it could potentially help catch bugs when the javascript files are changed (ie. if you generate the file it would be more obvious if something looks funny, or the generator can catch some problems at "compile"-time that wouldn't be apparent in the javascript until build time, etc.).

But I understand that it's more maintenance overhead and may not be something people want to deal with. Thanks again for your consideration.