Add JSDoc annotations to ensure enums type check even without .d.ts file

[RunDevelopment]

This is a partial fix for #3864.

I added additional JSDoc annotations to ensure that enums type check even without explicit type definition (.d.ts file).

C-style enums get an @enum {1|2|3|4} annotation which (1) marks the frozen enum object as an enum and (2) ensures that type annotations properly resolve. A comment in #3864 suggested using @enum {number}, but I defined the enum as the union of all possible numeric values instead to make the type more specific.

String enums get @typedef {"a" | "b" | "c"} StringEnum which is exactly the same as TS type StringEnum = "a" | "b" | "c". This means that string enums have exact type definitions with and without a .d.ts file. I also added @type {StringEnum[]} to arrays of string enum variants to ensure that the internal uses of those arrays don't cause type errors.

With those 2 changes, all of enum.js type checks without its .d.ts file.

One remaining problem is that I don't know how to test for the lack of type errors. While making this PR, I just added a // @ts-check at the top of enum.js so I could see type errors in my IDE. Any ideas how I could add tests for this?

[daxpedda]

@RunDevelopment if you rebase this PR, I'm happy to give it a review.

One remaining problem is that I don't know how to test for the lack of type errors. While making this PR, I just added a // @ts-check at the top of enum.js so I could see type errors in my IDE. Any ideas how I could add tests for this?

Unfortunately not.
I have almost no experience with JS/TS linting, but ideally all our output testing should be covered by them.

[RunDevelopment]

Rebased. Thank you for reviewing!

[RunDevelopment]

I've been think about this some more, and I think I'm going to remove the string enum JSDoc comments from this PR. This goal of this PR was to make sure that users of the generated JS don't have type errors, but the string enum changes are all about internal type errors (which don't affect users).

So I agree with the comment that the string enum stuff belongs in #4189, although I'll make a separate PR for it after #4189.

[daxpedda]

LGTM!
Missing a changelog entry.

[RunDevelopment]

Done, although I'm not sure whether the explanation I picked for this change is good...

[daxpedda]

Would appreciate if you could do the rebase!

[RunDevelopment]

Sure thing!