docs: standardize JSDoc class overviews across components#8617
Merged
Conversation
Aligns the class-level JSDoc of every public component in src/framework/components
with a common template based on the best-documented components (ElementComponent,
RigidBodyComponent):
- description paragraph(s)
- "You should never need to use the XxxComponent constructor directly..." disclaimer
- addComponent fenced example
- access-via-{@link Entity#xxx} paragraph + fenced example
- optional "Relevant Engine API examples:" bullet list (only when real examples exist)
- @hideconstructor and @category tags
Also fixes small nits encountered along the way (grammar, pc.Entity() -> new pc.Entity()).
ZoneComponent and JointComponent remain @ignore and only have their wording tidied.
Made-with: Cursor
Use the concise {@link propname} form when referencing a property of the
same class from within that class's JSDoc, instead of the verbose
{@link XxxComponent#propname} form.
- ElementComponent: {@link ElementComponent#type} -> {@link type}
- GSplatComponent: {@link GSplatComponent#unified} -> {@link unified}
- SpriteComponent: {@link SpriteComponent#type} -> {@link type}
Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes the class-level JSDoc overviews for framework components, aligning public component docs to a shared template (description, addComponent usage, entity.<component> access, and relevant example links) while keeping changes documentation-only.
Changes:
- Normalizes class overview JSDoc structure across many components (add/access examples, consistent prose).
- Fixes/standardizes example code patterns (notably
new pc.Entity()usage) and adds “Relevant Engine API examples” where available. - Adds missing
@hideconstructortags to a couple of public components.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/framework/components/zone/component.js | Refines overview prose (component remains @ignore). |
| src/framework/components/sprite/component.js | Expands overview to full template, adds type explanation and usage examples. |
| src/framework/components/scrollbar/component.js | Expands overview with add/access examples for Scrollbar. |
| src/framework/components/scroll-view/component.js | Expands overview with add/access examples and adds a relevant engine example link. |
| src/framework/components/script/component.js | Standardizes overview and converts access guidance into a structured entity.script example block. |
| src/framework/components/rigid-body/component.js | Fixes entity construction in examples (new pc.Entity()) and minor grammar. |
| src/framework/components/render/component.js | Adds @hideconstructor to match other public components. |
| src/framework/components/particle-system/component.js | Reflows/structures overview and adds add/access examples plus relevant engine example links. |
| src/framework/components/model/component.js | Adds missing @hideconstructor. |
| src/framework/components/light/component.js | Minor grammar fix in overview template line (“a LightComponent”). |
| src/framework/components/layout-group/component.js | Expands overview with add/access examples and relevant engine example link. |
| src/framework/components/layout-child/component.js | Expands overview with add/access examples (see review comment re: wording). |
| src/framework/components/joint/component.js | Refines overview prose (component remains @ignore). |
| src/framework/components/gsplat/component.js | Fixes entity construction in example (new pc.Entity()) and minor grammar. |
| src/framework/components/element/component.js | Fixes entity construction in example (new pc.Entity()). |
| src/framework/components/collision/component.js | Fixes entity construction in examples (new pc.Entity()) and minor grammar. |
| src/framework/components/camera/component.js | Adds “Relevant Engine API examples” section with links. |
| src/framework/components/button/component.js | Expands overview with add/access examples and relevant engine example links. |
| src/framework/components/audio-listener/component.js | Adds missing access-via-entity.audiolistener paragraph and example block. |
| src/framework/components/animation/component.js | Expands overview to full template and positions AnimationComponent as legacy vs AnimComponent. |
| src/framework/components/anim/component.js | Expands overview to full template and adds relevant engine example links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…portions" Addresses PR feedback: LayoutChildComponent exposes fit proportions via fitWidthProportion / fitHeightProportion, not a priority concept. Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Addresses PR feedback: the snippet described the scrollbar as draggable but did not enable input on the handle or wire a handle entity via handleEntity, so it would not actually be draggable. Update the example to mirror the canonical usage in examples/src/examples/user-interface/scroll-view.example.mjs: create a child handle entity with an input-enabled ElementComponent and pass it as handleEntity on the scrollbar. Made-with: Cursor
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 21 out of 21 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
Standardizes the class-level JSDoc overview of every public component in
src/framework/components/*/component.jsto a single common template derived from the best-documented components (ElementComponent,RigidBodyComponent).Each public component's class-level JSDoc now follows this structure:
You should never need to use the XxxComponent constructor directly. To add a XxxComponent to an {@link Entity}, use {@link Entity#addComponent}:addComponentexample (plus optional extra variants).Once the XxxComponent is added to the entity, you can access it via the {@link Entity#xxx} property:entity.xxx.Relevant Engine API examples:bullet list - only included when real examples exist onplaycanvas.github.io.@hideconstructorand@category.Changes by component
Gold-standard normalizations (grammar +
new pc.Entity()):element,rigid-body,collision,light,gsplatAdditive fixes:
camera: addedRelevant Engine API examples:section.render,model: added missing@hideconstructor.audio-listener: added the missing access-via-entity.audiolistenerparagraph and example.script: reshaped prose-only access description into a proper access-via-entity.scriptblock.Expanded from one-line descriptions to the full template:
sprite,button,scrollbar,scroll-view,layout-group,layout-child,animation,anim,particle-system@ignorecomponents (kept hidden, wording only tidied):zone,jointPublic API changes
None. This PR is documentation-only. No JSDoc annotations affecting generated TypeScript definitions (e.g. types, parameters, return values) have been changed; only class-level overview prose, fenced code examples and
@hideconstructor/@categorytags on component classes were touched.Test plan
SpriteComponent,CameraComponent,AudioListenerComponent) to confirm the new sections render correctly.