Skip to content

docs: fix more incorrect JSDoc in public APIs#8613

Merged
willeastcott merged 2 commits into
mainfrom
docs/jsdoc-public-api-fixes-2
Apr 19, 2026
Merged

docs: fix more incorrect JSDoc in public APIs#8613
willeastcott merged 2 commits into
mainfrom
docs/jsdoc-public-api-fixes-2

Conversation

@willeastcott

Copy link
Copy Markdown
Contributor

Summary

Follow-up to #8612. Another docs-only pass fixing objectively-wrong JSDoc and comment issues across the engine. No runtime behaviour changes.

Duplicate-word typos (14 sites)

Each is a one-word fix inside a JSDoc or shader-source comment line:

  • src/core/math/mat4.js — "the the matrix"
  • src/framework/bundle/bundle.js — "to to DataView"
  • src/framework/components/layout-group/component.js — "will be be rendered"
  • src/framework/xr/xr-anchor.js — "has has been persisted" (public @event)
  • src/platform/graphics/dynamic-buffers.js — "staging to to the GPU buffer"
  • src/platform/graphics/texture.js — "3 formats formats"
  • src/platform/graphics/uniform-buffer-format.js — "layout of of data"
  • src/platform/graphics/webgpu/webgpu-dynamic-buffers.js — "in the the command buffer"
  • src/scene/graphics/post-effect.js — "take a a render target"
  • src/scene/materials/standard-material.js (x2) — "will be be multiplied" on refractionVertexColor and thicknessVertexColor props
  • src/scene/shader-lib/programs/standard.js — "to to replace"
  • src/scene/shader-lib/glsl/chunks/render-pass/frag/sampleCatmullRom.js and its WGSL twin — "sample a a 4x4 grid" in shader source comments

Broken {@link} cross-reference

  • src/extras/gizmo/rotate-gizmo.js (2 sites) — @deprecated Use {@link RotationGizmo#rotationMode}. The class is RotateGizmo; RotationGizmo does not exist anywhere in src/. Fixed to {@link RotateGizmo#rotationMode}.

Missing word in applyForce description

  • src/framework/components/rigid-body/component.js (2 overload blocks) — "the force can be applied at an offset this point..." -> "...at an offset from this point...".

Incomplete @returns type

  • src/scene/mesh-instance.jsMeshInstance#getParameter returns this.parameters[name], which is undefined when the key is missing. Documented @returns {object} -> @returns {object|undefined} with a matching description. This mirrors the Compute#getParameter fix already merged in docs: fix incorrect JSDoc in public APIs #8612.

Public API changes

Only JSDoc changes; no runtime signatures change. One documented return type is widened:

Before:

/**
 * @returns {object} The named parameter.
 */
getParameter(name) { ... }

After:

/**
 * @returns {object|undefined} The named parameter, or `undefined` if no parameter with that
 * name is set on this mesh instance.
 */
getParameter(name) { ... }

Test plan

  • npx eslint on all 16 touched files passes.
  • No behavioural code changes; nothing else to test.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Docs-only follow-up that corrects objectively wrong JSDoc/comment text across multiple public APIs and shader-source comment blocks, improving generated documentation accuracy without affecting runtime behavior.

Changes:

  • Fixes multiple duplicated-word typos in JSDoc and shader comments across the engine.
  • Corrects broken {@link ...} references in RotateGizmo deprecation docs.
  • Clarifies documentation for MeshInstance#getParameter to include the undefined case, matching actual behavior.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
src/core/math/mat4.js Fixes duplicate-word typo in Mat4 documentation.
src/framework/bundle/bundle.js Fixes duplicate-word typo in Bundle internal index doc.
src/framework/components/layout-group/component.js Fixes duplicate-word typo in wrap/wrapping JSDoc.
src/framework/components/rigid-body/component.js Fixes missing word (“from”) in applyForce overload docs.
src/framework/xr/xr-anchor.js Fixes duplicate-word typo in public @event description.
src/extras/gizmo/rotate-gizmo.js Fixes broken {@link} reference in deprecated orbitRotation docs.
src/platform/graphics/dynamic-buffers.js Fixes duplicate-word typo in staging→GPU copy description.
src/platform/graphics/texture.js Fixes duplicate-word typo in WebGL2 renderability note.
src/platform/graphics/uniform-buffer-format.js Fixes duplicate-word typo in UniformBufferFormat descriptor doc.
src/platform/graphics/webgpu/webgpu-dynamic-buffers.js Fixes duplicate-word typo in staging-buffer lifecycle comment.
src/scene/graphics/post-effect.js Fixes duplicate-word typo in PostEffect class description.
src/scene/materials/standard-material.js Fixes duplicate-word typos in refraction/thickness vertex color docs.
src/scene/mesh-instance.js Updates getParameter return docs to include undefined when missing.
src/scene/shader-lib/programs/standard.js Fixes duplicate-word typo in shader generator JSDoc.
src/scene/shader-lib/glsl/chunks/render-pass/frag/sampleCatmullRom.js Fixes duplicate-word typo in GLSL shader-source comment.
src/scene/shader-lib/wgsl/chunks/render-pass/frag/sampleCatmullRom.js Fixes duplicate-word typo in WGSL shader-source comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/scene/graphics/post-effect.js Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@willeastcott willeastcott merged commit a7c9e26 into main Apr 19, 2026
12 checks passed
@willeastcott willeastcott deleted the docs/jsdoc-public-api-fixes-2 branch April 19, 2026 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants