More incremental improvements to JSDocs (#7619)

Author: willeastcott

src/core/shape/tri.js

@@ -14,7 +14,7 @@ const q = new Vec3();
 const EPSILON = 1e-6;
 
 /**
- * A triangle.
+ * A triangle defined by three {@link Vec3} vectors.
  *
  * @category Math
  */

src/core/tags.js

@@ -1,8 +1,13 @@
 import { EventHandler } from './event-handler.js';
 
 /**
- * Set of tag names. Tags are automatically available on {@link Entity} and {@link Asset} as `tags`
- * field.
+ * Tags is a powerful tag management system for categorizing and filtering objects in PlayCanvas
+ * applications. It provides an efficient way to attach string identifiers to objects and query them
+ * using logical operations.
+ *
+ * Tags are automatically available on {@link Asset}s and {@link Entity}s (see {@link Asset#tags}
+ * and {@link GraphNode#tags}). You can search for specific assets via {@link AssetRegistry#findByTag}
+ * and specific entities via {@link GraphNode#findByTag}.
  */
 class Tags extends EventHandler {
     /**

src/extras/render-passes/camera-frame.js

@@ -11,10 +11,9 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Rendering
  * Properties related to scene rendering, encompassing settings that control the rendering resolution,
  * pixel format, multi-sampling for anti-aliasing, tone-mapping and similar.
- *
- * @typedef {Object} Rendering
  * @property {number[]} renderFormats - The preferred render formats of the frame buffer, in order of
  * preference. First format from this list that is supported by the hardware is used. When none of
  * the formats are supported, {@link PIXELFORMAT_RGBA8} is used, but this automatically disables
@@ -52,12 +51,11 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Ssao
  * Properties related to the Screen Space Ambient Occlusion (SSAO) effect, a postprocessing technique
  * that approximates ambient occlusion by calculating how exposed each point in the screen space is
  * to ambient light, enhancing depth perception and adding subtle shadowing in crevices and between
  * objects.
- *
- * @typedef {Object} Ssao
  * @property {string} type - The type of the SSAO determines how it is applied in the rendering
  * process. Defaults to {@link SSAOTYPE_NONE}. Can be:
  *
@@ -77,11 +75,10 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Bloom
  * Properties related to the HDR bloom effect, a postprocessing technique that simulates the natural
  * glow of bright light sources by spreading their intensity beyond their boundaries, creating a soft
  * and realistic blooming effect.
- *
- * @typedef {Object} Bloom
  * @property {number} intensity - The intensity of the bloom effect, 0-0.1 range. Defaults to 0,
  * making it disabled.
  * @property {number} blurLevel - The number of iterations for blurring the bloom effect, with each
@@ -90,11 +87,10 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Grading
  * Properties related to the color grading effect, a postprocessing technique used to adjust and the
  * visual tone of an image. This effect modifies brightness, contrast, saturation, and overall color
  * balance to achieve a specific aesthetic or mood.
- *
- * @typedef {Object} Grading
  * @property {boolean} enabled - Whether grading is enabled. Defaults to false.
  * @property {number} brightness - The brightness of the grading effect, 0-3 range. Defaults to 1.
  * @property {number} contrast - The contrast of the grading effect, 0.5-1.5 range. Defaults to 1.
@@ -103,12 +99,11 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Vignette
  * Properties related to the vignette effect, a postprocessing technique that darkens the image
  * edges, creating a gradual falloff in brightness from the center outward. The effect can be also
  * reversed, making the center of the image darker than the edges, by specifying the outer distance
  * smaller than the inner distance.
- *
- * @typedef {Object} Vignette
  * @property {number} intensity - The intensity of the vignette effect, 0-1 range. Defaults to 0,
  * making it disabled.
  * @property {number} inner - The inner distance of the vignette effect measured from the center of
@@ -126,19 +121,17 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Fringing
  * Properties related to the fringing effect, a chromatic aberration phenomenon where the red, green,
  * and blue color channels diverge increasingly with greater distance from the center of the screen.
- *
- * @typedef {Object} Fringing
  * @property {number} intensity - The intensity of the fringing effect, 0-100 range. Defaults to 0,
  * making it disabled.
  */
 
 /**
+ * @typedef {Object} Taa
  * Properties related to temporal anti-aliasing (TAA), which is a technique used to reduce aliasing
  * in the rendered image by blending multiple frames together over time.
- *
- * @typedef {Object} Taa
  * @property {boolean} enabled - Whether TAA is enabled. Defaults to false.
  * @property {number} jitter - The intensity of the camera jitter, 0-1 range. The larger the value,
  * the more jitter is applied to the camera, making the anti-aliasing effect more pronounced. This
@@ -147,11 +140,10 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  */
 
 /**
+ * @typedef {Object} Dof
  * Properties related to Depth of Field (DOF), a technique used to simulate the optical effect where
  * objects at certain distances appear sharp while others are blurred, enhancing the perception of
  * focus and depth in the rendered scene.
- *
- * @typedef {Object} Dof
  * @property {boolean} enabled - Whether DoF is enabled. Defaults to false.
  * @property {boolean} nearBlur - Whether the near blur is enabled. Defaults to false.
  * @property {number} focusDistance - The distance at which the focus is set. Defaults to 100.

src/framework/components/scrollbar/data.js

@@ -14,7 +14,7 @@ class ScrollbarComponentData {
     /** @type {number} */
     handleSize = 0;
 
-    /** @type {Entity} */
+    /** @type {Entity|null} */
     handleEntity = null;
 }
 

src/framework/components/sound/slot.js

@@ -30,7 +30,8 @@ const instanceOptions = {
 };
 
 /**
- * The SoundSlot controls playback of an audio asset.
+ * The SoundSlot controls playback of an audio asset. A {@link SoundComponent} can have multiple
+ * slots that can be queried via {@link SoundComponent#slot}.
  *
  * @category Sound
  */

src/framework/components/sound/system.js

@@ -49,7 +49,7 @@ class SoundComponentSystem extends ComponentSystem {
 
     /**
      * Sets the volume for the entire Sound system. All sounds will have their volume multiplied by
-     * this value. Valid between [0, 1].
+     * this value. Valid range is between 0 and 1. Defaults to 1.
      *
      * @type {number}
      */

src/framework/xr/xr-manager.js

@@ -30,13 +30,20 @@ import { XrViews } from './xr-views.js';
 
 /**
  * @callback XrRoomCaptureCallback
- * Callback used by manual room capturing.
+ * Callback used by {@link XrManager#initiateRoomCapture}.
  * @param {Error|null} err - The Error object or null if manual room capture was successful.
  * @returns {void}
  */
 
 /**
- * Manage and update XR session and its states.
+ * XrManager provides a comprehensive interface for WebXR integration in PlayCanvas applications.
+ * It manages the full lifecycle of XR sessions (VR/AR), handles device capabilities, and provides
+ * access to various XR features through specialized subsystems.
+ *
+ * In order for XR to be available, ensure that your application is served over HTTPS or localhost.
+ *
+ * The {@link AppBase} class automatically creates an instance of this class and makes it available
+ * as {@link AppBase#xr}.
  *
  * @category XR
  */
@@ -229,7 +236,7 @@ class XrManager extends EventHandler {
     anchors;
 
     /**
-     * @type {CameraComponent}
+     * @type {CameraComponent|null}
      * @private
      */
     _camera = null;
@@ -337,6 +344,9 @@ class XrManager extends EventHandler {
      * callback when session is created or failed to create. Integrated XR APIs need to be enabled
      * by providing relevant options.
      *
+     * Note that the start method needs to be called in response to user action, such as a button
+     * click. It will not work if called in response to a timer or other event.
+     *
      * @param {CameraComponent} camera - It will be used to render XR session and manipulated based
      * on pose tracking.
      * @param {string} type - Session type. Can be one of the following:

src/platform/sound/sound.js

@@ -1,5 +1,7 @@
 /**
- * Represents the resource of an audio asset.
+ * Represents the raw audio data of playable sound. A Sound is the resource of an audio
+ * {@link Asset}. An audio asset can be assigned to a {@link SoundSlot} owned by a
+ * {@link SoundComponent}.
  *
  * @category Sound
  */

src/scene/materials/standard-material.js

@@ -41,9 +41,8 @@ let _params = new Set();
 const _tempColor = new Color();
 
 /**
- * Callback used by {@link StandardMaterial#onUpdateShader}.
- *
  * @callback UpdateShaderCallback
+ * Callback used by {@link StandardMaterial#onUpdateShader}.
  * @param {StandardMaterialOptions} options - An object with shader generator settings (based on current
  * material and scene properties), that you can change and then return. Properties of the object passed
  * into this function are documented in {@link StandardMaterial}. Also contains a member named litOptions