Docs: Add JSDoc config and improve Node docs.

[Mugen87]

Related issue: #24984

Description

There is an increasing interest in documentation for WebGPURenderer and the node material system so let's improve the situation by adding more docs.

To me, this is a good opportunity to start with adding JSDoc (see #24984 (comment)). The PR introduces a minimal JSDoc setup with a basic template that generates the documentation into docs_new. This directory is not under version control and not intended for hosting yet.

We can switch to a custom template at a later point with a style similar to the existing documentation. I'm ready for reviewing PRs that migrate existing modules next to WebGPURenderer or node material (anything in src or examples/jsm) to JSDoc. I'll will add more documentation by myself over the next weeks.

To move things forward I suggest we ignore i18n and TypeScript related details for now. The focus should be on providing an auto-generated English documentation based on JSDoc.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	339.14 78.99	339.14 78.99	+0 B +0 B
WebGPU	484.02 134.26	484.02 134.26	+0 B -1 B
WebGPU Nodes	483.49 134.16	483.49 134.16	+0 B -1 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	464.62 111.98	464.62 111.98	+0 B +0 B
WebGPU	552.83 149.53	552.83 149.53	+0 B +1 B
WebGPU Nodes	508.71 139.25	508.71 139.25	+0 B +0 B

[mrdoob]

Sounds good to me!
Thanks for working on this 🙏

[mrdoob]

Does JSDoc have a way to do this without polluting the source file?

[Mugen87]

Live examples

I have not seen something like this by default in JSDoc. However, the currently used theme has a demo that shows how to include live examples:

https://ankdev.me/clean-jsdoc-theme/v4/AgentArray.html

They have updated their JSDoc config so the build includes a custom JavaScript file that injects the iFrame into the final doc page. The script looks like so:

https://github.com/ankitskvmdam/clean-jsdoc-theme/blob/eebd46d31777106171ffa0573ae8825b228fab1d/demo/src/assets/agentarray.js#L8-L26

I guess we could do something similar with out material/geometry browsers.

@donmccurdy Do you know of other strategies for including live examples?

Code Snippets

Code example should already work nicely but they are normally embedded in the JSDoc. Since there is markdown support, the result looks without further CSS like so:

[donmccurdy]

Do you know of other strategies for including live examples?

I'm not aware of any convention for live examples that would work for off-the-shelf JSDoc themes. Perhaps we would want to find a JSDoc-to-HTML or JSDoc-to-JSON-to-HTML workflow that's flexible enough to support a custom handler for something like:

/**
 * ...
 * @example {@embed scenes/material-browser.html#MeshPhysicalMaterial}
 */
class MeshPhysicalMaterial extends MeshStandardMaterial {

}

The {@embed <url>} syntax is just an idea, based loosely on the often-used {@link <token>} syntax. For that matter, an HTML <iframe /> tag might 'just work' depending on the Markdown parser being used by the JSDoc theme.