Improve some JSDoc class descriptions (#6725)

* Improve some JSDoc class descriptions

* Lint fixes

* Improve GSplatComponent

* Remove redundant debugRender from GSplat examples

* Improve the Color class description

examples/src/examples/loaders/gsplat-many.example.mjs

@@ -75,7 +75,6 @@ assetListLoader.load(() => {
 
     const createSplatInstance = (name, resource, px, py, pz, scale, vertex, fragment) => {
         const splat = resource.instantiate({
-            debugRender: false,
             fragment: fragment,
             vertex: vertex
         });

examples/src/examples/loaders/gsplat.example.mjs

@@ -67,7 +67,6 @@ assetListLoader.load(() => {
 
     const createSplatInstance = (resource, px, py, pz, scale, vertex, fragment) => {
         const splat = resource.instantiate({
-            debugRender: false,
             fragment: fragment,
             vertex: vertex
         });

src/core/math/color.js

@@ -1,7 +1,11 @@
 import { math } from './math.js';
 
 /**
- * Representation of an RGBA color.
+ * An RGBA color.
+ *
+ * Each color component is a floating point value in the range 0 to 1. The `r` (red), `g` (green)
+ * and `b` (blue) components define a color in RGB color space. The `a` (alpha) component defines
+ * transparency. An alpha of 1 is fully opaque. An alpha of 0 is fully transparent.
  *
  * @category Math
  */

src/framework/components/element/component.js

@@ -31,7 +31,7 @@ const matC = new Mat4();
 const matD = new Mat4();
 
 /**
- * ElementComponents are used to construct user interfaces. An ElementComponent's [type](#type)
+ * 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
  * will be transformed with respect to the coordinate system of the screen. If there is no
@@ -69,6 +69,7 @@ const matD = new Mat4();
  * ```
  *
  * Relevant 'Engine-only' examples:
+ *
  * - [Basic text rendering](https://playcanvas.github.io/#/user-interface/text)
  * - [Auto font sizing](https://playcanvas.github.io/#/user-interface/text-auto-font-size)
  * - [Emojis](https://playcanvas.github.io/#/user-interface/text-emojis)

src/framework/components/gsplat/component.js

@@ -4,7 +4,14 @@ import { AssetReference } from '../../asset/asset-reference.js';
 import { Component } from '../component.js';
 
 /**
- * Enables an Entity to render a Gaussian Splat (asset of the 'gsplat' type).
+ * The GSplatComponent enables an {@link Entity} to render 3D Gaussian Splats. Splats are always
+ * loaded from {@link Asset}s rather than being created programmatically. The asset type is
+ * `gsplat` which are in the `.ply` file format.
+ *
+ * Relevant examples:
+ *
+ * - [Loading a Splat](https://playcanvas.github.io/#/loaders/gsplat)
+ * - [Custom Splat Shaders](https://playcanvas.github.io/#/loaders/gsplat-many)
  *
  * @category Graphics
  */

src/framework/components/render/component.js

@@ -15,8 +15,44 @@ import { Component } from '../component.js';
 import { EntityReference } from '../../utils/entity-reference.js';
 
 /**
- * Enables an Entity to render a {@link Mesh} or a primitive shape. This component attaches
- * {@link MeshInstance} geometry to the Entity.
+ * The RenderComponent enables an {@link Entity} to render 3D meshes. The {@link RenderComponent#type}
+ * property can be set to one of several predefined shape types (such as `box`, `sphere`, `cone`
+ * and so on). Alternatively, the component can be configured to manage an arbitrary array of
+ * {@link MeshInstance} objects. These can either be created programmatically or loaded from an
+ * {@link Asset}.
+ *
+ * You should never need to use the RenderComponent constructor directly. To add a RenderComponent
+ * to an Entity, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * // Add a render component to an entity with the default options
+ * const entity = new pc.Entity();
+ * entity.addComponent("render");  // This defaults to a 1x1x1 box
+ * ```
+ *
+ * To create an entity with a specific primitive shape:
+ *
+ * ```javascript
+ * entity.addComponent("render", {
+ *     type: "cone",
+ *     castShadows: false,
+ *     receiveShadows: false
+ * });
+ * ```
+ *
+ * Once the RenderComponent is added to the entity, you can set and get any of its properties:
+ *
+ * ```javascript
+ * entity.render.type = 'capsule';  // Set the render component's type
+ *
+ * console.log(entity.render.type); // Get the render component's type and print it
+ * ```
+ *
+ * Relevant examples:
+ *
+ * - [Spinning Cube](https://playcanvas.github.io/#/misc/hello-world)
+ * - [Primitive Shapes](https://playcanvas.github.io/#/graphics/shapes)
+ * - [Loading Render Assets](https://playcanvas.github.io/#/graphics/render-asset)
  *
  * @property {import('../../entity.js').Entity} rootBone A reference to the entity to be used as
  * the root bone for any skinned meshes that are rendered by this component.

src/framework/components/sound/component.js

@@ -7,7 +7,48 @@ import { Component } from '../component.js';
 import { SoundSlot } from './slot.js';
 
 /**
- * The Sound Component controls playback of {@link Sound}s.
+ * The SoundComponent enables an {@link Entity} to play audio. The SoundComponent can manage
+ * multiple {@link SoundSlot}s, each of which can play a different audio asset with its own set
+ * of properties such as volume, pitch, and looping behavior.
+ *
+ * The SoundComponent supports positional audio, meaning that the sound can be played relative
+ * to the Entity's position in 3D space. This is useful for creating immersive audio experiences
+ * where the sound's volume and panning are affected by the listener's position and orientation.
+ * Positional audio requires that an Entity with an {@link AudioListenerComponent} be added to the
+ * scene.
+ *
+ * You should never need to use the SoundComponent constructor directly. To add a SoundComponent
+ * to an Entity, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * // Add a sound component to an entity
+ * const entity = new pc.Entity();
+ * entity.addComponent("sound");
+ * ```
+ *
+ * Then, to add a sound slot to the component:
+ *
+ * ```javascript
+ * entity.sound.addSlot("beep", {
+ *     asset: asset,
+ *     autoPlay: true,
+ *     loop: true,
+ *     overlap: true,
+ *     pitch: 1.5
+ * });
+ * ```
+ *
+ * Once the SoundComponent is added to the entity, you can set and get any of its properties:
+ *
+ * ```javascript
+ * entity.sound.volume = 0.8;  // Set the volume for all sounds
+ *
+ * console.log(entity.sound.volume); // Get the volume and print it
+ * ```
+ *
+ * Relevant examples:
+ *
+ * - [Positional Sound](https://playcanvas.github.io/#/sound/positional)
  *
  * @category Sound
  */

src/framework/xr/xr-manager.js

@@ -804,7 +804,7 @@ class XrManager extends EventHandler {
         const deviceType = device.deviceType;
         if ((deviceType === DEVICETYPE_WEBGL1 || deviceType === DEVICETYPE_WEBGL2) && window.XRWebGLBinding) {
             try {
-                this.webglBinding = new XRWebGLBinding(this._session, device.gl); // eslint-disable-line no-undef
+                this.webglBinding = new XRWebGLBinding(this._session, device.gl);
             } catch (ex) {
                 this.fire('error', ex);
             }

src/scene/graph-node.js

@@ -87,7 +87,15 @@ function findNode(node, test) {
  */
 
 /**
- * A hierarchical scene node.
+ * The `GraphNode` class represents a node within a hierarchical scene graph. Each `GraphNode` can
+ * reference a array of child nodes. This creates a tree-like structure that is fundamental for
+ * organizing and managing the spatial relationships between objects in a 3D scene. This class
+ * provides a comprehensive API for manipulating the position, rotation, and scale of nodes both
+ * locally and in world space.
+ *
+ * `GraphNode` is the superclass of {@link Entity}, which is the primary class for creating objects
+ * in a PlayCanvas application. For this reason, `GraphNode` is rarely used directly, but it provides
+ * a powerful set of features that are leveraged by the `Entity` class.
  */
 class GraphNode extends EventHandler {
     /**