docs: document both halves of accessor pairs in public API#8634
Merged
Conversation
Follows the Mesh#aabb convention (independent JSDoc block with @type on each half of a get/set pair). Previously only one side was documented on a handful of public-API accessors. - Script.enabled - Sky.type, Sky.center, Sky.fisheye (plus depthWrite phrasing tidy) - GSplatParams.renderer, GSplatParams.debug - GSplatComponent.splatBudget (deprecated; matches adjacent lodDistances pair) - SingleGestureSource.layout, DualGestureSource.layout Also minor JSDoc tag reordering on Batch#model and GSplatParams#colorizeLod. Made-with: Cursor
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Aligns public API documentation for accessor pairs (get/set) with the engine’s JSDoc/TypeDoc convention by ensuring both halves have their own JSDoc blocks (including @type) and consistent “Sets…” / “Gets…” phrasing. This improves generated API reference consistency without changing runtime behavior.
Changes:
- Added missing JSDoc blocks (and
@type) for the getter half of multiple public accessors; rephrased setter docs for consistency. - Normalized / cleaned up deprecated accessor docs (tag ordering, missing
@type, and added@ignorewhere appropriate). - Minor copy edits to keep “Defaults…” and “Gets/Sets…” wording consistent across related properties.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/scene/skybox/sky.js | Adds getter JSDoc for type/center/fisheye and normalizes “Gets/Sets…” wording (incl. depthWrite). |
| src/scene/gsplat-unified/gsplat-params.js | Documents getter halves for renderer/debug; cleans up deprecated colorizeLod docs and adds @ignore. |
| src/scene/batching/batch.js | Reorders JSDoc tags on deprecated model getter. |
| src/framework/script/script.js | Adds getter JSDoc for enabled and rephrases setter documentation. |
| src/framework/components/gsplat/component.js | Ensures both halves of deprecated accessors carry consistent @type/@deprecated and adds @ignore. |
| src/extras/input/sources/single-gesture-source.js | Adds getter JSDoc for layout and normalizes wording. |
| src/extras/input/sources/dual-gesture-source.js | Expands setter JSDoc for layout and adds matching getter JSDoc. |
💡 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
Brings a handful of public-API accessors into line with the engine's documentation convention (demonstrated by
Mesh#aabbinsrc/scene/mesh.js), where both halves of aget/setpair carry their own JSDoc block and@type.The fix targets only accessors that actually appear in the generated API reference (classes with a class-level JSDoc block and no
@ignore/@private). Classes excluded from the API reference by TypeDoc'sexcludeNotDocumented: truewere left alone.Accessors updated
Script.enabled- setter rephrased to "Sets the enabled state...", matching getter added describing the AND of entity/component/destroyed state.Sky.type,Sky.center,Sky.fisheye- setters rephrased to "Sets the ...", matching getters added. While in the file,Sky.depthWritewas also retuned to "Sets whether..."/"Gets whether..." so all fourSkyaccessors read consistently.GSplatParams.renderer,GSplatParams.debug- setters rephrased to "Sets the ...", matching getters added. Therenderergetter notes the potential divergence fromcurrentRendererunder WebGL fallback.GSplatComponent.splatBudget- getter now carries the same@deprecated/@typeblock as the setter, matching the neighbouringlodDistancespair.SingleGestureSource.layout,DualGestureSource.layout- setters rephrased to "Sets the layout...", matching getters added. ForDualGestureSource, the previously bare@typesetter doc was expanded to describe the hyphen-separated left/right form and default.Incidental JSDoc cleanup
Batch#model: reordered JSDoc tags so@typeprecedes@deprecated/@ignore.GSplatParams#colorizeLod: added missing@type {boolean}on setter, normalized@returnsto@type {boolean}on getter, and added@ignore.Verification
@ignore/undocumented classes not exposed in the API reference).npm run lint- clean (one pre-existing unrelated warning inutils/rollup-build-target.mjs).npm run build:types-build/playcanvas.d.tsbuilds without errors.Public API changes
No behaviour changes. Documentation-only; all affected accessors keep the same name, type, and runtime semantics.