Declarations for engine and controller scripting API

[JoergAtGithub]

These declarations allow modern code editors and IDEs, to show online syntax help and allows type checking (as far as JavaScript supports types).

To enable this, the mapping developer has to create a file jsconfig.json in the directory with the JavaScript mapping to edit. This file is editor independend an should work with all editors, which support the Language Server Protocol (LSP), like VS Code, Atom, Eclipse, Kate, Sublime, etc.

The jsconfig.json must have the a content like below, that allows the editor to find all include files and tells him to use ES6 syntax:

{
  "compilerOptions": {
    "target": "es6",
    "checkJs": true,
    "lib": ["ES6"]
  },
  "include": ["<mappingpath>/Traktor-Kontrol-Z2-hid-scripts.js",
    "<mixxxpath>/res/controllers/common-hid-packet-parser.js",
    "<mixxxpath>/res/controllers/common-controller-scripts.js",
    "<mixxxpath>/res/controllers/hid-controller-api.d.ts",
    "<mixxxpath>/res/controllers/engine-api.d.ts",
    "<mixxxpath>/res/controllers/console-api.d.ts"]
}

[daschuer]

Sounds reasonable. Does this put any mandatory work to the mapping developer, that makes work harder as a noob contributor?

[JoergAtGithub]

Nothing mandatory, if you don't create the jsconfig.json file next to your mapping file, everything is as before.

[Swiftb0y]

Please ping me when this PR is ready for review. I'll take a look then.

[JoergAtGithub]

Please ping me when this PR is ready for review. I'll take a look then.

@Swiftb0y This is now ready for review!

[Swiftb0y]

Thank you very much for working on this DX improvement.
Please also link to some parts of our more elaborate docs on the github wiki.
Also, have you considered using plain JS files containing just JSDoc comments?
Also please add a comment to the *JSProxy-classes to point them to these definition files so they get updated when the proxy gets updated.

[Swiftb0y]

@JoergAtGithub please also take a look at my previous but abandoned attempt at this #2636

[JoergAtGithub]

@JoergAtGithub please also take a look at my previous but abandoned attempt at this #2636

Wasn't aware of this PR. I'm not at home this week, and will address your review comments the week after.

[Swiftb0y]

No problem. I just wanted to supply some context for my review comments.

[Swiftb0y]

thank you, just minor wording suggestions. I've tried to test this but I struggled getting it to work in my editor (vscodium). I'll get back to you once I figured out whats wrong.

[Swiftb0y]

After getting the jsconfig to work, I'm really annoyed by the fact that a developer needs to edit the jsconfig to reference their mapping in order for everything to work. After a bit of research and trial and error, I don't think there is anything we can do against that, right?

We could get that working by making each mapping their own project (which would make sense) but that would require putting each mapping to its own folder. That's something I would like to do anyways in the future, but is out-of-scope for this PR.

I think we should include a jsconfig as well. Putting this into res/controllers/ should work:

{
    "compilerOptions": {
        "target": "es6",
        "checkJs": true,
        "lib": ["ES6"]
    },
    "include": [
        "*.d.ts",
        "common-hid-packet-parser.js",
        "common-controller-scripts.js",

        // add the filename of your own mapping here:
        ""

        // make sure to exclude any changes in this file from your submission
    ]
}

[JoergAtGithub]

I would not like to add a jsconfig.json in the scope of this PR.

[Swiftb0y]

I would not like to add a jsconfig.json in the scope of this PR.

Thats fair. Though it certainly makes it more difficult to test.

[Swiftb0y]

thank you, last couple complaints I found.

[Swiftb0y]

Indentation looks good to me. LGTM otherwise. Thank you for your patience.

[JoergAtGithub]

Done

[Swiftb0y]

LGTM, thank you.

[JoergAtGithub]

Time to celebrate twice - the PR is exactly 1 year old today. 🎂

[Swiftb0y]

Sorry, this took this long... Highly appreciate the effort though.

[JoergAtGithub]

Thank you for the review!