docs: simplify self-referential JSDoc @link tags#8624
Merged
Conversation
Drop the `ClassName#` prefix from `{@link ClassName#member}` tags when they
appear inside that class's own JSDoc (class-level, field, accessor, or method
block). TypeDoc resolves bare `{@link member}` against the enclosing class, so
the generated docs are unchanged and the source reads more cleanly.
Module-scope JSDoc blocks (`@callback`, `@typedef`, standalone functions /
constants) and cross-class references are left untouched.
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
This PR simplifies self-referential JSDoc {@link ...} tags across the engine by removing redundant ClassName# qualifiers where TypeDoc can resolve member links against the enclosing class, and reflows a few affected comment lines to keep formatting tidy without changing rendered documentation output.
Changes:
- Replaced
{@link ClassName#member}with{@link member}in class-scoped JSDoc blocks (properties, accessors, methods, and class-level docs). - Preserved fully-qualified links for cross-class/module references while shortening intra-class references.
- Reflowed select JSDoc paragraphs after link shortening to avoid awkward wrapping.
Reviewed changes
Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/scene/scene.js | Simplifies Scene’s self-referential @link tags (e.g., skybox, ambientBake) and reflows related text. |
| src/scene/mesh.js | Simplifies Mesh method links (setPositions, setUvs, update) in Mesh API docs and method docs. |
| src/scene/materials/standard-material.js | Simplifies StandardMaterial property cross-references inside its class JSDoc. |
| src/scene/materials/material.js | Simplifies Material’s self-referential links (blendType, depthTest, getShaderChunks) in property/method docs. |
| src/scene/layer.js | Simplifies Layer internal references (enabled, decrementCounter) within member docs. |
| src/scene/gsplat-unified/gsplat-params.js | Simplifies GSplatParams self-links (e.g., debug, lodUpdateAngle, radialSorting) and reflows lines. |
| src/scene/graphics/quad-render.js | Simplifies QuadRender’s render link within class doc and reflows the paragraph. |
| src/scene/graphics/fisheye-projection.js | Simplifies FisheyeProjection’s update link in the class doc and reflows lines. |
| src/scene/composition/layer-composition.js | Simplifies LayerComposition references to layerList within class member docs. |
| src/scene/batching/batch-manager.js | Simplifies BatchManager self-links (prepare, create) and reflows parameter descriptions. |
| src/platform/sound/instance.js | Simplifies SoundInstance self-links to setExternalNodes in related method docs. |
| src/platform/input/mouse.js | Simplifies Mouse self-link to enablePointerLock in static helper docs. |
| src/platform/graphics/render-target.js | Simplifies RenderTarget self-link to resolve in constructor option docs. |
| src/platform/graphics/graphics-device.js | Simplifies GraphicsDevice self-links (e.g., supportsSubgroups, maxPixelRatio) and reflows wrapped text. |
| src/platform/graphics/draw-commands.js | Simplifies DrawCommands self-links (add, update) in class doc. |
| src/framework/xr/xr-view.js | Simplifies XrView self-links to depthUvMatrix in event/property docs. |
| src/framework/xr/xr-input-source.js | Simplifies XrInputSource self-links (elementInput, grip) and reflows wrapped text. |
| src/framework/scene-registry.js | Simplifies SceneRegistry self-links (find, loadSceneHierarchy, etc.) in method docs. |
| src/framework/i18n/i18n.js | Simplifies I18n self-links (getText, getPluralText, addData) in class/method docs. |
| src/framework/handlers/handler.js | Simplifies ResourceHandler self-link to load in open method docs. |
| src/framework/graphics/picker.js | Simplifies Picker self-links (prepare, getSelectionAsync, getSelection) in class/method docs. |
| src/framework/components/system.js | Simplifies ComponentSystem self-link to addComponent and reflows description. |
| src/framework/components/sound/component.js | Simplifies SoundComponent self-link to resume in pause method docs. |
| src/framework/components/render/component.js | Simplifies RenderComponent self-link to hide and reflows text. |
| src/framework/components/particle-system/component.js | Simplifies ParticleSystemComponent self-link to play in autoPlay docs. |
| src/framework/components/model/component.js | Simplifies ModelComponent self-link to hide and reflows text. |
| src/framework/components/light/component.js | Simplifies LightComponent self-link to numCascades and reflows description. |
| src/framework/components/layout-group/component.js | Simplifies LayoutGroupComponent self-links (widthFitting, heightFitting) and reflows text. |
| src/framework/components/gsplat/component.js | Simplifies GSplatComponent self-links (material, hide) and reflows note text. |
| src/framework/components/camera/component.js | Simplifies CameraComponent self-link to framePasses in deprecated alias docs. |
| src/extras/gizmo/translate-gizmo.js | Simplifies TranslateGizmo self-link to flipPlanes in deprecated alias docs. |
| src/extras/gizmo/transform-gizmo.js | Simplifies TransformGizmo self-links in deprecated alias docs and method return text. |
| src/extras/gizmo/scale-gizmo.js | Simplifies ScaleGizmo self-link to flipPlanes in deprecated alias docs. |
| src/extras/gizmo/rotate-gizmo.js | Simplifies RotateGizmo self-link to rotationMode in deprecated alias docs. |
| src/core/math/mat4.js | Simplifies Mat4 self-link to mul2 in method docs. |
| src/core/block-allocator.js | Simplifies BlockAllocator self-links (updateAllocation, allocate) and reflows wrapped text. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- transform-gizmo.js: keep explicit link to Gizmo#coordSpace since the
member is inherited from the base class, not declared on TransformGizmo.
- xr-view.js: fix a pre-existing grammar slip on a line touched by this PR
("texture been resized" -> "texture has been resized").
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 36 out of 36 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
alphaFade is declared on StandardMaterial (not Material), so the link could never resolve to the documented member. Since the @Property block is already inside StandardMaterial's own class JSDoc, simplify to the bare form consistent with the rest of this PR. Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 36 out of 36 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ClassName#prefix from{@link ClassName#member}tags when the tag sits inside that class's own JSDoc (class-level block, fields, accessors, or methods). TypeDoc resolves bare{@link member}against the enclosing class, so the generated docs are unchanged while the source reads more cleanly.@callback/@typedefblocks, standalone function/constant JSDoc, and JSDoc of other classes in multi-class files. Cross-class references (e.g. links to a base class from a subclass file) are also untouched.Scope
36 files touched across
src/:camera,gsplat,light,layout-group,particle-system,render,model,sound,system,rigid-body/systemscene,layer,mesh,composition/layer-composition,batching/batch-manager,graphics/quad-render,graphics/fisheye-projection,gsplat-unified/gsplat-params,materials/material,materials/standard-materialscene-registry,handlers/handler,graphics/picker,i18n/i18nxr-input-source,xr-viewgraphics/graphics-device,graphics/render-target,graphics/draw-commands,graphics/depth-state,sound/instance,input/mouserotate-gizmo,translate-gizmo,scale-gizmo,transform-gizmomath/mat4,block-allocatorTest plan
npm run lintclean on the touched files (2 unrelated pre-existing lint errors intest/gltf-roundtrip/roundtrip-test.mjsremain onmain)npm run build:typessucceedsnpm run docsproduces the same 9 pre-existing TypeDoc warnings asmain(verified by comparing the warning set against a clean checkout — no new unresolved-link warnings)