docs: standardize JSDoc class overviews across components

src/framework/components/anim/component.js

@@ -13,8 +13,40 @@ import {
 import { AnimTrack } from '../../anim/evaluator/anim-track.js';
 
 /**
- * The AnimComponent allows an {@link Entity} to playback animations on models and entity
- * properties.
+ * The AnimComponent enables an {@link Entity} to play back animations on models and entity
+ * properties. Animations are driven by animation state graphs, which can be authored in the
+ * PlayCanvas Editor or constructed programmatically, and support blending between multiple
+ * layers and clips.
+ *
+ * You should never need to use the AnimComponent constructor directly. To add an AnimComponent
+ * to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('anim', {
+ *     activate: true,
+ *     speed: 1
+ * });
+ * ```
+ *
+ * Once the AnimComponent is added to the entity, you can access it via the {@link Entity#anim}
+ * property:
+ *
+ * ```javascript
+ * entity.anim.speed = 2; // Play animations at double speed
+ *
+ * console.log(entity.anim.speed); // Get the playback speed and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [1D Blend Trees](https://playcanvas.github.io/#/animation/blend-trees-1d)
+ * - [2D Cartesian Blend Trees](https://playcanvas.github.io/#/animation/blend-trees-2d-cartesian)
+ * - [2D Directional Blend Trees](https://playcanvas.github.io/#/animation/blend-trees-2d-directional)
+ * - [Animation Events](https://playcanvas.github.io/#/animation/events)
+ * - [Component Properties](https://playcanvas.github.io/#/animation/component-properties)
+ * - [Layer Masks](https://playcanvas.github.io/#/animation/layer-masks)
+ * - [Locomotion](https://playcanvas.github.io/#/animation/locomotion)
  *
  * @hideconstructor
  * @category Animation

src/framework/components/animation/component.js

@@ -13,7 +13,29 @@ import { Component } from '../component.js';
  */
 
 /**
- * The Animation Component allows an Entity to playback animations on models.
+ * The AnimationComponent enables an {@link Entity} to play back skeletal animations on a model.
+ * It is a legacy component that has largely been superseded by {@link AnimComponent}, which
+ * supports more advanced features such as animation state graphs and blending.
+ *
+ * You should never need to use the AnimationComponent constructor directly. To add an
+ * AnimationComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('animation', {
+ *     assets: [animationAsset.id],
+ *     speed: 1
+ * });
+ * ```
+ *
+ * Once the AnimationComponent is added to the entity, you can access it via the
+ * {@link Entity#animation} property:
+ *
+ * ```javascript
+ * entity.animation.speed = 2; // Play the animation at double speed
+ *
+ * console.log(entity.animation.speed); // Get the playback speed and print it
+ * ```
  *
  * @hideconstructor
  * @category Animation

src/framework/components/audio-listener/component.js

@@ -13,6 +13,15 @@ import { Component } from '../component.js';
  * entity.addComponent('audiolistener');
  * ```
  *
+ * Once the AudioListenerComponent is added to the entity, you can access it via the
+ * {@link Entity#audiolistener} property:
+ *
+ * ```javascript
+ * entity.audiolistener.enabled = false; // Disable the audio listener
+ *
+ * console.log(entity.audiolistener.enabled); // Get the enabled state and print it
+ * ```
+ *
  * Relevant Engine API examples:
  *
  * - [Positional Sound](https://playcanvas.github.io/#/sound/positional)

src/framework/components/button/component.js

@@ -43,8 +43,36 @@ STATES_TO_SPRITE_FRAME_NAMES[VisualState.PRESSED] = 'pressedSpriteFrame';
 STATES_TO_SPRITE_FRAME_NAMES[VisualState.INACTIVE] = 'inactiveSpriteFrame';
 
 /**
- * A ButtonComponent enables a group of entities to behave like a button, with different visual
- * states for hover and press interactions.
+ * The ButtonComponent enables an {@link Entity} to behave like a button, with different visual
+ * states for hover and press interactions. It is designed to be used together with an
+ * {@link ElementComponent} on the same entity, which provides the button's visual appearance and
+ * input hit area.
+ *
+ * You should never need to use the ButtonComponent constructor directly. To add a
+ * ButtonComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('element', {
+ *     type: pc.ELEMENTTYPE_IMAGE,
+ *     useInput: true
+ * });
+ * entity.addComponent('button');
+ * ```
+ *
+ * Once the ButtonComponent is added to the entity, you can access it via the
+ * {@link Entity#button} property:
+ *
+ * ```javascript
+ * entity.button.hoverTint = pc.Color.YELLOW; // Set the hover tint color
+ *
+ * console.log(entity.button.hoverTint);      // Get the hover tint color and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Basic Button](https://playcanvas.github.io/#/user-interface/button-basic)
+ * - [Sprite Button](https://playcanvas.github.io/#/user-interface/button-sprite)
  *
  * @hideconstructor
  * @category User Interface

src/framework/components/camera/component.js

@@ -60,6 +60,13 @@ import { PostEffectQueue } from './post-effect-queue.js';
  * console.log(entity.camera.nearClip); // Get the near clip of the camera
  * ```
  *
+ * Relevant Engine API examples:
+ *
+ * - [First Person Camera](https://playcanvas.github.io/#/camera/first-person)
+ * - [Fly Camera](https://playcanvas.github.io/#/camera/fly)
+ * - [Multiple Cameras](https://playcanvas.github.io/#/camera/multi)
+ * - [Orbit Camera](https://playcanvas.github.io/#/camera/orbit)
+ *
  * @hideconstructor
  * @category Graphics
  */

src/framework/components/collision/component.js

@@ -22,18 +22,18 @@ const _quat = new Quat();
  * When an entity is configured as a trigger volume, if an entity with a dynamic or kinematic body
  * enters or leaves that trigger volume, both entities will receive trigger events.
  *
- * You should never need to use the CollisionComponent constructor directly. To add an
+ * You should never need to use the CollisionComponent constructor directly. To add a
  * CollisionComponent to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript
- * const entity = pc.Entity();
+ * const entity = new pc.Entity();
  * entity.addComponent('collision'); // This defaults to 1x1x1 box-shaped trigger volume
  * ```
  *
  * To create a 0.5 radius dynamic rigid body sphere:
  *
  * ```javascript
- * const entity = pc.Entity();
+ * const entity = new pc.Entity();
  * entity.addComponent('collision', {
  *     type: 'sphere'
  * });

src/framework/components/element/component.js

@@ -38,9 +38,9 @@ const matC = new Mat4();
 const matD = new Mat4();
 
 /**
- * ElementComponents are used to construct user interfaces. The {@link ElementComponent#type}
- * property can be configured in 3 main ways: as a text element, as an image element or as a group
- * element. If the ElementComponent has a {@link ScreenComponent} ancestor in the hierarchy, it
+ * ElementComponents are used to construct user interfaces. The {@link type} property can be
+ * configured in 3 main ways: as a text element, as an image element or as a group element. If
+ * the ElementComponent has a {@link ScreenComponent} ancestor in the hierarchy, it
  * will be transformed with respect to the coordinate system of the screen. If there is no
  * {@link ScreenComponent} ancestor, the ElementComponent will be transformed like any other
  * entity.
@@ -49,7 +49,7 @@ const matD = new Mat4();
  * ElementComponent to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript
- * const entity = pc.Entity();
+ * const entity = new pc.Entity();
  * entity.addComponent('element'); // This defaults to a 'group' element
  * ```
  *

src/framework/components/gsplat/component.js

@@ -26,11 +26,11 @@ import { PickerId } from '../../../scene/picker-id.js';
  * `gsplat` which supports multiple file formats including `.ply`, `.sog`, `.meta.json` (SOG
  * format), and `.lod-meta.json` (streaming LOD format).
  *
- * You should never need to use the GSplatComponent constructor directly. To add an
+ * You should never need to use the GSplatComponent constructor directly. To add a
  * GSplatComponent to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript
- * const entity = pc.Entity();
+ * const entity = new pc.Entity();
  * entity.addComponent('gsplat', {
  *     asset: asset
  * });
@@ -47,8 +47,8 @@ import { PickerId } from '../../../scene/picker-id.js';
  *
  * ## Unified Rendering
  *
- * The {@link GSplatComponent#unified} property enables unified rendering mode, which provides
- * advanced features for Gaussian Splats:
+ * The {@link unified} property enables unified rendering mode, which provides advanced features
+ * for Gaussian Splats:
  *
  * - **Global Sorting**: Multiple splat components are sorted together in a single unified sort,
  *   eliminating visibility artifacts and popping effects when splat components overlap.

src/framework/components/joint/component.js

@@ -28,7 +28,8 @@ const properties = [
 ];
 
 /**
- * The JointComponent adds a physics joint constraint linking two rigid bodies.
+ * The JointComponent enables an {@link Entity} to act as a physics joint constraint that links
+ * two rigid bodies, controlling the relative motion between them.
  *
  * @ignore
  */

src/framework/components/layout-child/component.js

@@ -1,8 +1,33 @@
 import { Component } from '../component.js';
 
 /**
- * A LayoutChildComponent enables the Entity to control the sizing applied to it by its parent
- * {@link LayoutGroupComponent}.
+ * The LayoutChildComponent enables an {@link Entity} to control the sizing and fitting behavior
+ * applied to it by its parent {@link LayoutGroupComponent}. It allows per-child overrides of
+ * minimum and maximum dimensions as well as fit proportions.
+ *
+ * You should never need to use the LayoutChildComponent constructor directly. To add a
+ * LayoutChildComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('element', {
+ *     type: pc.ELEMENTTYPE_IMAGE
+ * });
+ * entity.addComponent('layoutchild', {
+ *     minWidth: 50,
+ *     maxWidth: 200,
+ *     fitWidthProportion: 1
+ * });
+ * ```
+ *
+ * Once the LayoutChildComponent is added to the entity, you can access it via the
+ * {@link Entity#layoutchild} property:
+ *
+ * ```javascript
+ * entity.layoutchild.minWidth = 80; // Increase the minimum width
+ *
+ * console.log(entity.layoutchild.minWidth); // Get the minimum width and print it
+ * ```
  *
  * @hideconstructor
  * @category User Interface

src/framework/components/layout-group/component.js

@@ -20,8 +20,36 @@ function isEnabledAndHasEnabledElement(entity) {
 }
 
 /**
- * A LayoutGroupComponent enables the Entity to position and scale child {@link ElementComponent}s
- * according to configurable layout rules.
+ * The LayoutGroupComponent enables an {@link Entity} to position and scale its child
+ * {@link ElementComponent}s according to configurable layout rules. It supports horizontal and
+ * vertical orientations and a variety of alignment, spacing, wrapping and sizing options.
+ *
+ * You should never need to use the LayoutGroupComponent constructor directly. To add a
+ * LayoutGroupComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('element', {
+ *     type: pc.ELEMENTTYPE_GROUP
+ * });
+ * entity.addComponent('layoutgroup', {
+ *     orientation: pc.ORIENTATION_HORIZONTAL,
+ *     spacing: new pc.Vec2(10, 0)
+ * });
+ * ```
+ *
+ * Once the LayoutGroupComponent is added to the entity, you can access it via the
+ * {@link Entity#layoutgroup} property:
+ *
+ * ```javascript
+ * entity.layoutgroup.spacing = new pc.Vec2(20, 0); // Increase spacing between children
+ *
+ * console.log(entity.layoutgroup.spacing);         // Get the spacing and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Layout Group](https://playcanvas.github.io/#/user-interface/layout-group)
  *
  * @hideconstructor
  * @category User Interface

src/framework/components/light/component.js

@@ -25,7 +25,7 @@ import { properties } from './data.js';
  * - `spot`: A local light that emits light similarly to an omni light but is bounded by a cone
  * centered on the owner entity's negative y-axis. Emulates flashlights, spotlights, etc.
  *
- * You should never need to use the LightComponent constructor directly. To add an LightComponent
+ * You should never need to use the LightComponent constructor directly. To add a LightComponent
  * to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript

src/framework/components/model/component.js

@@ -48,6 +48,7 @@ import { Component } from '../component.js';
  * console.log(entity.model.type); // Get the model component's type and print it
  * ```
  *
+ * @hideconstructor
  * @category Graphics
  */
 class ModelComponent extends Component {

src/framework/components/particle-system/component.js

@@ -90,19 +90,50 @@ const ASSET_PROPERTIES = ['colorMapAsset', 'normalMapAsset', 'meshAsset', 'rende
 let depthLayer;
 
 /**
- * Used to simulate particles and produce renderable particle mesh on either CPU or GPU. GPU
- * simulation is generally much faster than its CPU counterpart, because it avoids slow CPU-GPU
- * synchronization and takes advantage of many GPU cores. However, it requires client to support
- * reasonable uniform count, reading from multiple textures in vertex shader and OES_texture_float
- * extension, including rendering into float textures. Most mobile devices fail to satisfy these
- * requirements, so it's not recommended to simulate thousands of particles on them. GPU version
- * also can't sort particles, so enabling sorting forces CPU mode too. Particle rotation is
- * specified by a single angle parameter: default billboard particles rotate around camera facing
- * axis, while mesh particles rotate around 2 different view-independent axes. Most of the
- * simulation parameters are specified with {@link Curve} or {@link CurveSet}. Curves are
- * interpolated based on each particle's lifetime, therefore parameters are able to change over
- * time. Most of the curve parameters can also be specified by 2 minimum/maximum curves, this way
- * each particle will pick a random value in-between.
+ * The ParticleSystemComponent enables an {@link Entity} to simulate particles and produce a
+ * renderable particle mesh on either CPU or GPU. GPU simulation is generally much faster than
+ * its CPU counterpart, because it avoids slow CPU-GPU synchronization and takes advantage of
+ * many GPU cores. However, it requires client support for reasonable uniform counts, reading
+ * from multiple textures in a vertex shader and the OES_texture_float extension, including
+ * rendering into float textures. Most mobile devices fail to satisfy these requirements, so it's
+ * not recommended to simulate thousands of particles on them. The GPU version also can't sort
+ * particles, so enabling sorting forces CPU mode too.
+ *
+ * Particle rotation is specified by a single angle parameter: default billboard particles rotate
+ * around the camera-facing axis, while mesh particles rotate around two different view-independent
+ * axes. Most of the simulation parameters are specified with {@link Curve} or {@link CurveSet}.
+ * Curves are interpolated based on each particle's lifetime, therefore parameters are able to
+ * change over time. Most curve parameters can also be specified by 2 minimum/maximum curves, so
+ * that each particle picks a random value in-between.
+ *
+ * You should never need to use the ParticleSystemComponent constructor directly. To add a
+ * ParticleSystemComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('particlesystem', {
+ *     numParticles: 100,
+ *     lifetime: 2,
+ *     rate: 0.1
+ * });
+ * ```
+ *
+ * Once the ParticleSystemComponent is added to the entity, you can access it via the
+ * {@link Entity#particlesystem} property:
+ *
+ * ```javascript
+ * entity.particlesystem.loop = false; // Play the system once then stop
+ *
+ * console.log(entity.particlesystem.loop); // Get the loop flag and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Particle Animated Index](https://playcanvas.github.io/#/graphics/particles-anim-index)
+ * - [Particle Mesh](https://playcanvas.github.io/#/graphics/particles-mesh)
+ * - [Particle Random Sprites](https://playcanvas.github.io/#/graphics/particles-random-sprites)
+ * - [Particle Snow](https://playcanvas.github.io/#/graphics/particles-snow)
+ * - [Particle Spark](https://playcanvas.github.io/#/graphics/particles-spark)
  *
  * @hideconstructor
  * @category Graphics

src/framework/components/render/component.js

@@ -55,6 +55,7 @@ import { Component } from '../component.js';
  * - [Primitive Shapes](https://playcanvas.github.io/#/graphics/shapes)
  * - [Spinning Cube](https://playcanvas.github.io/#/misc/hello-world)
  *
+ * @hideconstructor
  * @category Graphics
  */
 class RenderComponent extends Component {