Add JSDoc for Box2

[Methuselah96]

Related issue: #24984 (comment)

Description

A proof-of-concept for adding JSDoc (the .d.ts file is built by running npm run build-types, it wouldn't actually be committed if we go with this approach)

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	685.24 169.64	685.24 169.64	+0 B +0 B
WebGPU	826.2 221.55	826.2 221.55	+0 B +0 B
WebGPU Nodes	825.78 221.46	825.78 221.46	+0 B +0 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	462.02 111.48	462.02 111.48	+0 B +0 B
WebGPU	525.3 141.56	525.3 141.56	+0 B +0 B
WebGPU Nodes	481.95 131.37	481.95 131.37	+0 B +0 B

[mrdoob]

I think as long as we do not force contributors to have to write these I think it may be okay.

But I'm afraid we'll end up having discussions about types in the repo again and that would slow us down.

Are you trying to look for ways to offload the maintenance of types?

[Mugen87]

I would expect we primarily write JSDoc to generate the English API documentation. It is a nice side effect that we can also use JSDoc to generate TS declaration files. However, the actual generation and hosting/providing should be done in a different repository and npm package (three-ts-types).

In this way, discussions about the TS related topics happen at a different place. We can accept PRs to improve the typings in the scope of JSDoc.

[Methuselah96]

@Mugen87 is exactly right. The goal is also to make maintenance of the translated docs easier. Making it easier to create TS declaration files is not a goal, it's just a nice side-effect, so any discussion of TS types should still happen in three-ts-types.

The other option that has been discussed would be to host the types and the documentation in a different repo together (.d.ts+TSDoc), but I think this is the better split so you can ignore TypeScript altogether, just mentioning it in case you find that appealing.