Investigate alternative libraries for type generation than `jsdoc`
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 40.3k
- Forks
- 7.2k
- PR merge metrics
- No merged PRs in 30d
Description
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),tscwould likely be the best means of generating types for us.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by examining the tsgen parser and its reliance on the jsdoc CLI. Compare viable alternative libraries against the stated tuple and negative-number limitations, while considering the note about using tsc after a TypeScript conversion. Done means documenting a supported, maintainable direction for replacing or retaining jsdoc.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- documentation, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100