docs: improve JSDoc documentation in utils.js #32743

Angel98518 · 2026-01-13T22:47:35Z

Add comprehensive JSDoc comments for array utility functions (arrayMin, arrayMax, arrayNeedsUint32)
Document typed array utilities (TYPED_ARRAYS constant and getTypedArray function)
Add documentation for DOM element creation functions (createElementNS, createCanvasElement)
Document console logging system (setConsoleFunction, getConsoleFunction, log, warn, error, warnOnce)
Add detailed JSDoc for WebGL synchronization function (probeAsync)
Document projection matrix conversion functions (toNormalizedProjectionMatrix, toReversedProjectionMatrix)
Include parameter types, return types, and detailed descriptions for all documented functions

This improves code maintainability and helps developers understand the purpose and usage of utility functions.

Related issue: #XXXX

Description

A clear and concise description of what the problem was and how this pull request solves it.

This contribution is funded by Example

- Add comprehensive JSDoc comments for array utility functions (arrayMin, arrayMax, arrayNeedsUint32) - Document typed array utilities (TYPED_ARRAYS constant and getTypedArray function) - Add documentation for DOM element creation functions (createElementNS, createCanvasElement) - Document console logging system (setConsoleFunction, getConsoleFunction, log, warn, error, warnOnce) - Add detailed JSDoc for WebGL synchronization function (probeAsync) - Document projection matrix conversion functions (toNormalizedProjectionMatrix, toReversedProjectionMatrix) - Include parameter types, return types, and detailed descriptions for all documented functions This improves code maintainability and helps developers understand the purpose and usage of utility functions.

github-actions · 2026-01-13T22:49:58Z

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	355.57 84.48	355.57 84.48	+0 B +0 B
WebGPU	621.09 172.46	621.09 172.46	+0 B +0 B
WebGPU Nodes	619.7 172.22	619.7 172.22	+0 B +0 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	487.81 119.38	487.81 119.38	+0 B +0 B
WebGPU	692.03 187.85	692.03 187.85	+0 B +0 B
WebGPU Nodes	641.83 175.02	641.83 175.02	+0 B +0 B

Mugen87 · 2026-01-14T09:02:27Z

src/utils.js

+ *
+ * @param {Array<number>} array - The array to search for the minimum value.
+ * @return {number} The minimum value in the array, or Infinity if the array is empty.
+ */


Except for createCanvasElement(), setConsoleFunction(), getConsoleFunction(), log(), warn(), error(), warnOnce(), none of these functions are part of the public API so add the @private tag to them.

You mean that Except for createCanvasElement(), setConsoleFunction(), getConsoleFunction(), log(), warn(), error(), warnOnce(), add @Private tag?

@Mugen87

As requested by @Mugen87, marking all documented utility functions as @Private since they are not part of the public API.

Mugen87 · 2026-01-14T13:18:16Z

src/utils.js

+ * display style set to 'block', which is commonly used in three.js
+ * rendering contexts to avoid inline element spacing issues.
+ *
+ * @private


The exported functions should not be private, see

three.js/src/Three.Core.js

Line 162 in e90650f

export { createCanvasElement, setConsoleFunction, getConsoleFunction, log, warn, error, warnOnce } from './utils.js';

all exported functions should not be private?

Yes, these can be used by the developer and should be part of the public documentation.

Mugen87 · 2026-01-14T13:18:48Z

src/utils.js

+ * Map of typed array constructor names to their constructors.
+ * This mapping enables dynamic creation of typed arrays based on string type names.
+ *
+ * @constant


This should be private as well.

@Mugen87

As requested by @Mugen87, removed @Private tags from all exported utility functions since they are part of the public API.

@Mugen87

As requested by @Mugen87, added @Private tag to functions that are not part of the public API: - arrayMin, arrayMax, arrayNeedsUint32 - getTypedArray - createCanvasElement - probeAsync - toNormalizedProjectionMatrix, toReversedProjectionMatrix Public API functions (without @Private): - createElementNS, setConsoleFunction, getConsoleFunction - log, warn, error, warnOnce

@Private

- Add @Private to TYPED_ARRAYS constant (as requested) - Remove @Private from createCanvasElement() since it's exported

@Private

Removed @Private tags from all exported functions as requested: - arrayMin, arrayMax, arrayNeedsUint32 - getTypedArray - probeAsync - toNormalizedProjectionMatrix, toReversedProjectionMatrix TYPED_ARRAYS constant keeps @Private as it's not exported.

Angel98518 · 2026-01-14T13:46:01Z

I have fixed feedback. Please check

Mugen87 · 2026-01-14T13:48:24Z

This ins't correct since a lot of private tags are missing.

@Mugen87

As requested by @Mugen87, added @Private tags to functions that are NOT part of the public API. Public API functions (no @Private): - createCanvasElement, setConsoleFunction, getConsoleFunction - log, warn, error, warnOnce Private functions (with @Private): - arrayMin, arrayMax, arrayNeedsUint32 - getTypedArray, createElementNS - probeAsync - toNormalizedProjectionMatrix, toReversedProjectionMatrix - TYPED_ARRAYS constant

Angel98518 · 2026-01-14T14:00:32Z

This ins't correct since a lot of private tags are missing.

Fixed this. Could you check again please?
Sorry

Angel98518 · 2026-01-14T15:49:44Z

@Mugen87
Can you check my updates?

Mugen87 · 2026-01-14T15:58:28Z

src/utils.js

+/**
+ * Internal cache for tracking warning messages to prevent duplicate warnings.
+ *
+ * @type {Object<string, boolean>}


This should be private as well.

Mugen87 · 2026-01-14T15:58:41Z

src/utils.js

+/**
+ * Custom console function handler for intercepting log, warn, and error calls.
+ *
+ * @type {Function|null}


And add private here.

Fixed this.

@Private

Added @Private tags to: - _cache constant (internal warning message cache) - _setConsoleFunction variable (internal console function handler) These are internal implementation details and should be marked as private.

Angel98518 · 2026-01-14T18:14:50Z

Hi.
@Mugen87
What about my updates?

fix: remove trailing spaces from JSDoc comments

1137b96

Mugen87 reviewed Jan 14, 2026

View reviewed changes

docs: add @Private tag to all utility functions

83f33ee

As requested by @Mugen87, marking all documented utility functions as @Private since they are not part of the public API.

Mugen87 reviewed Jan 14, 2026

View reviewed changes

Daniel added 4 commits January 14, 2026 14:36

docs: remove @Private tags from exported functions

d45dcb4

As requested by @Mugen87, removed @Private tags from all exported utility functions since they are part of the public API.

docs: fix @Private tags per maintainer feedback

8e25708

- Add @Private to TYPED_ARRAYS constant (as requested) - Remove @Private from createCanvasElement() since it's exported

Mugen87 reviewed Jan 14, 2026

View reviewed changes

docs: add @Private tags to internal constants and variables

da59099

Added @Private tags to: - _cache constant (internal warning message cache) - _setConsoleFunction variable (internal console function handler) These are internal implementation details and should be marked as private.

Uh oh!

docs: improve JSDoc documentation in utils.js #32743

Are you sure you want to change the base?

docs: improve JSDoc documentation in utils.js #32743

Conversation

Angel98518 commented Jan 13, 2026

Uh oh!

github-actions bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Bundle size

🌳 Bundle size after tree-shaking

Uh oh!

Mugen87 Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Angel98518 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Mugen87 Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Angel98518 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Mugen87 Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mugen87 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Angel98518 commented Jan 14, 2026

Uh oh!

Mugen87 commented Jan 14, 2026

Uh oh!

Angel98518 commented Jan 14, 2026

Uh oh!

Angel98518 commented Jan 14, 2026

Uh oh!

Mugen87 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Mugen87 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Angel98518 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Angel98518 commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Jan 13, 2026 •

edited

Loading

Mugen87 Jan 14, 2026 •

edited

Loading

Mugen87 Jan 14, 2026 •

edited

Loading

Mugen87 Jan 14, 2026 •

edited

Loading