phaserjs / phaserjs/phaser

Investigate alternative libraries for type generation than `jsdoc`

Open
#7,298 8 comments 0 reactions 0 assignees View on GitHub

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), tsc would likely be the best means of generating types for us.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.