docs: remove redundant JSDoc @type tags from inferable fields#8625
Merged
Conversation
Removes @type tags on class fields whose initializer already provides unambiguous type inference to TypeScript: - Primitive literals (numbers, booleans, strings) - Arithmetic/Math expressions and Number() coercions - Boolean coercions (!!x, typeof X !== 'undefined', equality checks) - new Vec2/Vec3/Vec4/Quat/Mat3/Mat4/Color/Ray/BoundingBox/BoundingSphere/Plane/Frustum - .clone() calls on the corresponding concrete class Fields marked @readonly are left untouched (literal types are preserved on readonly fields, so the @type tag is not redundant there). build/playcanvas.d.ts is byte-identical to before these changes (verified after stripping @type cosmetic comment lines). test:types passes. TypeDoc output is unchanged apart from a few newly-written descriptions for fields that previously carried only an @type annotation. Made-with: Cursor
- pose.js: added descriptions for pitch/yaw/x/y/zRange fields - gsplat-octree-node.js: added description for bounds field - sky-mesh.js: removed empty block on _depthWrite (field is private-style inside an @ignore class, so it does not appear in the API docs; the .d.ts output is unchanged) Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reduces JSDoc noise across the engine by removing redundant @type annotations from class fields where TypeScript can unambiguously infer the type from the initializer, while keeping important tags like @private, @ignore, and @readonly intact.
Changes:
- Remove redundant
@typetags for inferable field initializers (primitives,new ..., etc.). - Collapse some JSDoc blocks that only carried tags (for example to
/** @private *///** @ignore */). - Add short descriptive text in a few places where JSDoc previously only had a
@typetag.
Reviewed changes
Copilot reviewed 139 out of 139 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/scene/skybox/sky.js | Remove inferable @type from private fields. |
| src/scene/skybox/sky-mesh.js | Remove inferable @type and simplify field JSDoc. |
| src/scene/shader-lib/shader-chunks.js | Remove inferable @type from version. |
| src/scene/shader-lib/programs/lit-shader.js | Remove inferable @type from varyingsCode. |
| src/scene/shader-lib/programs/lit-shader-options.js | Remove inferable @type tags from options fields. |
| src/scene/scene.js | Remove inferable @type tags from scene config fields. |
| src/scene/renderer/render-pass-forward.js | Remove inferable @type from noDepthClear. |
| src/scene/morph-target.js | Remove inferable @type from used. |
| src/scene/mesh.js | Remove inferable @type tags from private fields. |
| src/scene/mesh-instance.js | Remove inferable @type tags and simplify tag-only JSDoc. |
| src/scene/materials/standard-material-options.js | Remove inferable @type tags from material options. |
| src/scene/materials/material.js | Remove inferable @type tags from material fields. |
| src/scene/light.js | Remove inferable @type from ignored numeric field. |
| src/scene/layer.js | Remove inferable @type tags and simplify private flags JSDoc. |
| src/scene/gsplat/gsplat-streams.js | Remove inferable @type tags from private fields. |
| src/scene/gsplat/gsplat-sog-resource.js | Collapse tag-only JSDoc to one-line. |
| src/scene/gsplat/gsplat-sog-data.js | Remove inferable @type tags from config fields. |
| src/scene/gsplat/gsplat-resource-base.js | Remove inferable @type tags and simplify private counters JSDoc. |
| src/scene/gsplat/gsplat-format.js | Remove inferable @type tags from flags/counters. |
| src/scene/gsplat/gsplat-container.js | Remove inferable @type tags from private counters. |
| src/scene/gsplat-unified/gsplat-world-state.js | Remove inferable @type tags from state fields. |
| src/scene/gsplat-unified/gsplat-work-buffer.js | Collapse tag-only @ignore JSDoc to one-line. |
| src/scene/gsplat-unified/gsplat-sort-key-compute.js | Remove inferable @type tags from fields. |
| src/scene/gsplat-unified/gsplat-sort-bin-weights.js | Remove inferable @type tags from cached values. |
| src/scene/gsplat-unified/gsplat-renderer.js | Remove inferable @type from protected version cache. |
| src/scene/gsplat-unified/gsplat-placement.js | Remove inferable @type tags from placement fields. |
| src/scene/gsplat-unified/gsplat-params.js | Remove inferable @type tags and simplify private field JSDoc. |
| src/scene/gsplat-unified/gsplat-octree.resource.js | Remove inferable @type from ignored version field. |
| src/scene/gsplat-unified/gsplat-octree.js | Remove inferable @type tags from counters/flags. |
| src/scene/gsplat-unified/gsplat-octree-node.js | Replace type-only JSDoc with descriptive text where applicable. |
| src/scene/gsplat-unified/gsplat-octree-instance.js | Remove inferable @type tags from instance state fields. |
| src/scene/gsplat-unified/gsplat-manager.js | Remove inferable @type tags from manager state fields. |
| src/scene/gsplat-unified/gsplat-interval-compaction.js | Remove inferable @type and simplify private-method JSDoc. |
| src/scene/gsplat-unified/gsplat-info.js | Remove inferable @type tags from counters/indices. |
| src/scene/gsplat-unified/gsplat-frustum-culler.js | Remove inferable @type tags from numeric fields. |
| src/scene/graphics/render-pass-radix-sort-reorder.js | Remove inferable @type tags from pass config fields. |
| src/scene/graphics/render-pass-radix-sort-count.js | Remove inferable @type tags from pass config fields. |
| src/scene/graphics/post-effect.js | Remove inferable @type from constructor-initialized field. |
| src/scene/graphics/frame-pass-radix-sort.js | Remove inferable @type tags from private fields. |
| src/scene/graphics/fisheye-projection.js | Remove inferable @type tags from projection parameters. |
| src/scene/graphics/compute-radix-sort.js | Remove inferable @type tags from private fields. |
| src/scene/graph-node.js | Remove inferable @type tags and simplify private/internal JSDoc. |
| src/scene/fog-params.js | Remove inferable @type tags from fog params. |
| src/scene/constants.js | Collapse tag-only @ignore JSDoc for constants. |
| src/scene/animation/skeleton.js | Remove inferable @type from looping. |
| src/scene/animation/animation.js | Remove inferable @type tags from animation fields. |
| src/platform/sound/listener.js | Remove inferable @type tags and simplify private field JSDoc. |
| src/platform/sound/instance3d.js | Remove inferable @type tags and simplify private field JSDoc. |
| src/platform/sound/instance.js | Remove inferable @type tags and simplify private field JSDoc. |
| src/platform/input/mouse-event.js | Remove inferable @type tags from event fields. |
| src/platform/input/game-pads.js | Remove inferable @type tags from button state fields. |
| src/platform/graphics/webgpu/webgpu-upload-stream.js | Remove inferable @type from private version cache. |
| src/platform/graphics/webgpu/webgpu-render-target.js | Remove inferable @type tags from flags. |
| src/platform/graphics/webgpu/webgpu-graphics-device.js | Remove inferable @type tags from private counters. |
| src/platform/graphics/uniform-buffer.js | Remove inferable @type from renderVersionDirty. |
| src/platform/graphics/uniform-buffer-format.js | Collapse tag-only @ignore JSDoc for byteSize. |
| src/platform/graphics/texture.js | Remove inferable @type from ignored version field. |
| src/platform/graphics/stencil-parameters.js | Remove inferable @type and simplify private dirty flag JSDoc. |
| src/platform/graphics/render-pass.js | Remove inferable @type tags from ops fields. |
| src/platform/graphics/graphics-device.js | Remove inferable @type tags and simplify tag-only JSDoc. |
| src/platform/graphics/gpu-profiler.js | Remove inferable @type from maxCount. |
| src/platform/graphics/frame-pass.js | Remove inferable @type tags from internal flags. |
| src/platform/graphics/draw-commands.js | Remove inferable @type tags and simplify tag-only method JSDoc. |
| src/platform/graphics/depth-state.js | Remove inferable @type from key. |
| src/platform/graphics/compute.js | Remove inferable @type tags and simplify tag-only JSDoc. |
| src/platform/graphics/bind-group.js | Remove inferable @type from private render-version field. |
| src/platform/graphics/bind-group-format.js | Remove inferable @type tags and simplify tag-only JSDoc. |
| src/framework/xr/xr-views.js | Remove inferable @type tags and simplify private method/field JSDoc. |
| src/framework/xr/xr-view.js | Remove inferable @type tags and simplify private method/field JSDoc. |
| src/framework/xr/xr-tracked-image.js | Remove inferable @type tags and simplify private/ignore field JSDoc. |
| src/framework/xr/xr-plane.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-plane-detection.js | Remove inferable @type and simplify private availability flag JSDoc. |
| src/framework/xr/xr-mesh.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-mesh-detection.js | Remove inferable @type and simplify private availability flag JSDoc. |
| src/framework/xr/xr-manager.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-light-estimation.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-joint.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-input.js | Collapse tag-only @ignore JSDoc on field. |
| src/framework/xr/xr-input-source.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-image-tracking.js | Remove inferable @type and simplify private availability flag JSDoc. |
| src/framework/xr/xr-hit-test.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-hand.js | Remove inferable @type and simplify private tracking flag JSDoc. |
| src/framework/xr/xr-anchors.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/xr/xr-anchor.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/input/element-input.js | Remove inferable @type from wheel delta field. |
| src/framework/handlers/untar.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/handlers/handler.js | Remove inferable @type from handlerType. |
| src/framework/graphics/picker.js | Remove inferable @type from private device-valid flag. |
| src/framework/font/font.js | Remove inferable @type from constructor field. |
| src/framework/entity.js | Remove inferable @type tags from ignored flags. |
| src/framework/components/rigid-body/system.js | Collapse tag-only @ignore and remove inferable @type. |
| src/framework/components/render/component.js | Remove inferable @type from isStatic. |
| src/framework/components/model/component.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/framework/components/gsplat/gsplat-asset-loader.js | Remove inferable @type tags from loader config. |
| src/framework/components/gsplat/component.js | Remove inferable @type tags from private LOD/unified fields. |
| src/framework/components/camera/post-effect-queue.js | Remove inferable @type from ignored enabled flag. |
| src/framework/components/camera/component.js | Remove inferable @type tags from private counters. |
| src/framework/components/animation/component.js | Remove inferable @type tags from animation fields. |
| src/framework/bundle/bundle.js | Remove inferable @type from private loaded flag. |
| src/framework/asset/asset.js | Remove inferable @type tags from asset load state fields. |
| src/framework/app-base.js | Remove inferable @type tags and simplify tag-only @ignore JSDoc. |
| src/extras/render-passes/render-pass-taa.js | Remove inferable @type from historyIndex. |
| src/extras/render-passes/render-pass-ssao.js | Remove inferable @type tags from SSAO parameters. |
| src/extras/render-passes/frame-pass-camera-frame.js | Remove inferable @type from ignored layersDirty. |
| src/extras/input/sources/virtual-joystick.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/extras/input/sources/single-gesture-source.js | Collapse tag-only @override JSDoc to one-line. |
| src/extras/input/sources/multi-touch-source.js | Remove inferable @type tags and simplify private fields JSDoc. |
| src/extras/input/sources/keyboard-mouse-source.js | Remove inferable @type tags and collapse tag-only JSDoc. |
| src/extras/input/sources/gamepad-source.js | Collapse tag-only @override JSDoc to one-line. |
| src/extras/input/sources/dual-gesture-source.js | Collapse tag-only @override JSDoc to one-line. |
| src/extras/input/pose.js | Replace type-only JSDoc with descriptions for range fields. |
| src/extras/input/controllers/orbit-controller.js | Remove inferable @type tags from damping fields. |
| src/extras/input/controllers/focus-controller.js | Remove inferable @type from damping field. |
| src/extras/input/controllers/fly-controller.js | Remove inferable @type tags from damping fields. |
| src/extras/gizmo/view-cube.js | Remove inferable @type tags and simplify private fields/method JSDoc. |
| src/extras/gizmo/tri-data.js | Remove inferable @type tags from internal fields. |
| src/extras/gizmo/translate-gizmo.js | Collapse tag-only @override/@private JSDoc; remove inferable @type. |
| src/extras/gizmo/transform-gizmo.js | Remove inferable @type tags and collapse tag-only JSDoc. |
| src/extras/gizmo/shape/sphere-shape.js | Collapse tag-only @ignore; remove inferable @type. |
| src/extras/gizmo/shape/shape.js | Collapse tag-only @ignore; remove inferable @type tags. |
| src/extras/gizmo/shape/plane-shape.js | Collapse tag-only @ignore; remove inferable @type tags. |
| src/extras/gizmo/shape/boxline-shape.js | Collapse tag-only @ignore; remove inferable @type tags. |
| src/extras/gizmo/shape/box-shape.js | Collapse tag-only @ignore; remove inferable @type. |
| src/extras/gizmo/shape/arrow-shape.js | Collapse tag-only @ignore; remove inferable @type tags. |
| src/extras/gizmo/shape/arc-shape.js | Collapse tag-only @ignore; remove inferable @type tags. |
| src/extras/gizmo/scale-gizmo.js | Remove inferable @type tags and collapse tag-only JSDoc. |
| src/extras/gizmo/rotate-gizmo.js | Remove inferable @type tags and collapse tag-only JSDoc. |
| src/extras/gizmo/mesh-line.js | Collapse tag-only @ignore; simplify private field JSDoc. |
| src/extras/gizmo/gizmo.js | Remove inferable @type tags and collapse tag-only JSDoc. |
| src/extras/exporters/gltf-exporter.js | Collapse tag-only @ignore JSDoc. |
| src/core/sorted-loop-array.js | Remove inferable @type tags from numeric fields. |
| src/core/shape/plane.js | Remove inferable @type from normal. |
| src/core/shape/oriented-box.js | Remove inferable @type and simplify private field JSDoc. |
| src/core/shape/bounding-box.js | Remove inferable @type and simplify private fields JSDoc. |
| src/core/ref-counted-object.js | Remove inferable @type and simplify private field JSDoc. |
| src/core/object-pool.js | Remove inferable @type from private counter. |
| src/core/math/curve.js | Remove inferable @type from tension. |
| src/core/event-handle.js | Remove inferable @type from private removed flag. |
| src/core/block-allocator.js | Remove inferable @type tags from private fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 139 out of 139 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.
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 139 out of 139 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
Removes ~500 redundant JSDoc
@typetags on class fields whose initializer already provides unambiguous type inference to TypeScript. No public API changes;build/playcanvas.d.tsis byte-identical after stripping the removed@typecomment lines, and TypeDoc output is unchanged (a few fields that previously carried only an@typeannotation now carry a short description instead).What was removed
@typetags were removed from fields where the right-hand side is one of:= 0,= 1.5,= true,= false,= 'x'Math.PI,Math.clamp(...),Number(x)!!x,typeof X !== 'undefined',env === 'browser'new Vec2/Vec3/Vec4/Quat/Mat3/Mat4/Color/Ray/BoundingBox/BoundingSphere/Plane/Frustum(...).clone()calls on the corresponding concrete class (e.g.Vec3.UP.clone(),COLOR_RED.clone())Fields marked
@readonlyare deliberately left untouched — TypeScript preserves the literal type on readonly fields, so the@typetag is load-bearing there.Verification
npm run build:typessucceedsnpm run test:typessucceedsbuild/playcanvas.d.tstype declarations are byte-identical tomain(after filtering out@typecosmetic comment lines, which naturally disappear when the source tags are removed)Test plan
npm run build:typesnpm run test:typesmain