Investigate alternative libraries for type generation than `jsdoc`

[Bertie690]

Moving away

It has come to my attention that the jsdoc CLI that the tsgen parser relies on has more or less died off given its commit history has effectively stopped.
With the only activity being dependency version bumps, it appears there is little hope of the project adding support for things like tuples or negative numbers, both of which serve as major limitations towards documenting Phaser's own API. (For instance, we physically cannot type RandomDataGenerator#sign with the 2 values it is contractually obligated to return as jsdoc will crash when trying to parse the union -1 | 1).

Unless a major revival is launched in the near future (which it likely won't be), it may be wise to start thinking of alternate means of generating type documentation long-term. (I'd strongly advise against an in-house solution as the current one is ALREADY incomprehensible as is.)

I have created this issue as a "discussion board" of sorts to discuss various options for moving towards a more functional (and ideally better-maintained) solution for typegen that doesn't curb expressivity.

Note

If the repository is ever converted to pure TypeScript OR plain JavaScript (by which I mean actual ESM classes and not "fake" class-building functions), tsc would likely be the best means of generate types for us.

[niklas-e]

Good point! I've always wondered why projects have been declaring types in any other way than native TypeScript. It is just generally fragile. Anyways, I could contribute to Phaser TS migration. I think it doesn't even need to be all-in migration at first, because you can configure TypeScript to allow JavaScript modules.