API Reference improvements and fixes (#7499)

* API Reference improvements and fixes

* Lint fix

* More edits

* Update audio listener overview

* More updates

* Tweak RenderComponent

* Tweak ScriptComponent

* Tweaks

* Lint fix

* Fix a TypeDoc warning

* Fix tests on Windows

* Fix more TypeDoc warnings

* Rewrite application-related class descriptions

* Whitspace

* Tweak

* Tweaks

* Update Entity class description

* Improve the ComponentSystemRegistry class description

* Tweak

* Fix a TypeDoc warning

* Fix two more TypeDoc warnings

Author: willeastcott

package.json

@@ -124,7 +124,7 @@
     "lint": "eslint scripts src test utils build.mjs eslint.config.mjs rollup.config.mjs",
     "publint": "publint --level error",
     "serve": "serve build -l 51000 --cors",
-    "test": "mocha --ignore 'test/assets/scripts/**' --recursive --require test/fixtures.mjs --timeout 5000",
+    "test": "mocha --ignore \"test/assets/scripts/*.js\" --recursive --require test/fixtures.mjs --timeout 5000",
     "test:coverage": "c8 npm test",
     "test:types": "tsc --pretty false build/playcanvas.d.ts"
   },

src/core/event-handler.js

@@ -4,14 +4,14 @@ import { EventHandle } from './event-handle.js';
  * Callback used by {@link EventHandler} functions. Note the callback is limited to 8 arguments.
  *
  * @callback HandleEventCallback
- * @param {*} [arg1] - First argument that is passed from caller.
- * @param {*} [arg2] - Second argument that is passed from caller.
- * @param {*} [arg3] - Third argument that is passed from caller.
- * @param {*} [arg4] - Fourth argument that is passed from caller.
- * @param {*} [arg5] - Fifth argument that is passed from caller.
- * @param {*} [arg6] - Sixth argument that is passed from caller.
- * @param {*} [arg7] - Seventh argument that is passed from caller.
- * @param {*} [arg8] - Eighth argument that is passed from caller.
+ * @param {any} [arg1] - First argument that is passed from caller.
+ * @param {any} [arg2] - Second argument that is passed from caller.
+ * @param {any} [arg3] - Third argument that is passed from caller.
+ * @param {any} [arg4] - Fourth argument that is passed from caller.
+ * @param {any} [arg5] - Fifth argument that is passed from caller.
+ * @param {any} [arg6] - Sixth argument that is passed from caller.
+ * @param {any} [arg7] - Seventh argument that is passed from caller.
+ * @param {any} [arg8] - Eighth argument that is passed from caller.
  */
 
 /**
@@ -259,14 +259,14 @@ class EventHandler {
      * Fire an event, all additional arguments are passed on to the event listener.
      *
      * @param {string} name - Name of event to fire.
-     * @param {*} [arg1] - First argument that is passed to the event handler.
-     * @param {*} [arg2] - Second argument that is passed to the event handler.
-     * @param {*} [arg3] - Third argument that is passed to the event handler.
-     * @param {*} [arg4] - Fourth argument that is passed to the event handler.
-     * @param {*} [arg5] - Fifth argument that is passed to the event handler.
-     * @param {*} [arg6] - Sixth argument that is passed to the event handler.
-     * @param {*} [arg7] - Seventh argument that is passed to the event handler.
-     * @param {*} [arg8] - Eighth argument that is passed to the event handler.
+     * @param {any} [arg1] - First argument that is passed to the event handler.
+     * @param {any} [arg2] - Second argument that is passed to the event handler.
+     * @param {any} [arg3] - Third argument that is passed to the event handler.
+     * @param {any} [arg4] - Fourth argument that is passed to the event handler.
+     * @param {any} [arg5] - Fifth argument that is passed to the event handler.
+     * @param {any} [arg6] - Sixth argument that is passed to the event handler.
+     * @param {any} [arg7] - Seventh argument that is passed to the event handler.
+     * @param {any} [arg8] - Eighth argument that is passed to the event handler.
      * @returns {EventHandler} Self for chaining.
      * @example
      * obj.fire('test', 'This is the message');

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

@@ -35,7 +35,7 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  * used together at a higher cost. Defaults to 1.
  * @property {boolean} sceneColorMap - Whether rendering generates a scene color map. Defaults to false.
  * @property {boolean} sceneDepthMap - Whether rendering generates a scene depth map. Defaults to false.
- * @property {number} toneMapping - The tone mapping. Defaults to {@link ToneMapping.LINEAR}. Can be:
+ * @property {number} toneMapping - The tone mapping. Can be:
  *
  * - {@link TONEMAP_LINEAR}
  * - {@link TONEMAP_FILMIC}
@@ -44,6 +44,7 @@ import { CameraFrameOptions, RenderPassCameraFrame } from './render-pass-camera-
  * - {@link TONEMAP_ACES2}
  * - {@link TONEMAP_NEUTRAL}
  *
+ * Defaults to {@link TONEMAP_LINEAR}.
  * @property {number} sharpness - The sharpening intensity, 0-1 range. This can be used to increase
  * the sharpness of the rendered image. Often used to counteract the blurriness of the TAA effect,
  * but also blurriness caused by rendering to a lower resolution render target by using

src/framework/app-base.js

@@ -106,28 +106,21 @@ import { getApplication, setApplication } from './globals.js';
 let app = null;
 
 /**
- * An Application represents and manages your PlayCanvas application. If you are developing using
- * the PlayCanvas Editor, the Application is created for you. You can access your Application
- * instance in your scripts. Below is a skeleton script which shows how you can access the
- * application 'app' property inside the initialize and update functions:
+ * AppBase represents the base functionality for all PlayCanvas applications. It is responsible for
+ * initializing and managing the application lifecycle. It coordinates core engine systems such
+ * as:
  *
- * ```javascript
- * // Editor example: accessing the pc.Application from a script
- * var MyScript = pc.createScript('myScript');
+ * - The graphics device - see {@link GraphicsDevice}.
+ * - The asset registry - see {@link AssetRegistry}.
+ * - The component system registry - see {@link ComponentSystemRegistry}.
+ * - The scene - see {@link Scene}.
+ * - Input devices - see {@link Keyboard}, {@link Mouse}, {@link TouchDevice}, and {@link GamePads}.
+ * - The main update/render loop.
  *
- * MyScript.prototype.initialize = function() {
- *     // Every script instance has a property 'this.app' accessible in the initialize...
- *     const app = this.app;
- * };
- *
- * MyScript.prototype.update = function(dt) {
- *     // ...and update functions.
- *     const app = this.app;
- * };
- * ```
- *
- * If you are using the Engine without the Editor, you have to create the application instance
- * manually.
+ * Using AppBase directly requires you to register {@link ComponentSystem}s and
+ * {@link ResourceHandler}s yourself. This facilitates
+ * [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) when bundling
+ * your application.
  */
 class AppBase extends EventHandler {
     /**
@@ -288,8 +281,8 @@ class AppBase extends EventHandler {
 
     /**
      * Set to true to render the scene on the next iteration of the main loop. This only has an
-     * effect if {@link AppBase#autoRender} is set to false. The value of renderNextFrame is set
-     * back to false again as soon as the scene has been rendered.
+     * effect if {@link autoRender} is set to false. The value of renderNextFrame is set back to
+     * false again as soon as the scene has been rendered.
      *
      * @type {boolean}
      * @example
@@ -449,11 +442,11 @@ class AppBase extends EventHandler {
     /**
      * Create a new AppBase instance.
      *
-     * @param {HTMLCanvasElement} canvas - The canvas element.
+     * @param {HTMLCanvasElement | OffscreenCanvas} canvas - The canvas element.
      * @example
-     * // Engine-only example: create the application manually
-     * const options = new AppOptions();
      * const app = new pc.AppBase(canvas);
+     *
+     * const options = new AppOptions();
      * app.init(options);
      *
      * // Start the application's main loop

src/framework/app-options.js

@@ -14,8 +14,8 @@
  */
 
 /**
- * AppOptions is an object that holds configuration settings utilized in the creation of AppBase. It
- * allows functionality to be included or excluded from the AppBase instance.
+ * AppOptions holds configuration settings utilized in the creation of an {@link AppBase} instance.
+ * It allows functionality to be included or excluded from the AppBase instance.
  */
 class AppOptions {
     /**

src/framework/application.js

@@ -65,28 +65,11 @@ import { XrManager } from './xr/xr-manager.js';
  */
 
 /**
- * An Application represents and manages your PlayCanvas application. If you are developing using
- * the PlayCanvas Editor, the Application is created for you. You can access your Application
- * instance in your scripts. Below is a skeleton script which shows how you can access the
- * application 'app' property inside the initialize and update functions:
- *
- * ```javascript
- * // Editor example: accessing the pc.Application from a script
- * var MyScript = pc.createScript('myScript');
- *
- * MyScript.prototype.initialize = function() {
- *     // Every script instance has a property 'this.app' accessible in the initialize...
- *     const app = this.app;
- * };
- *
- * MyScript.prototype.update = function(dt) {
- *     // ...and update functions.
- *     const app = this.app;
- * };
- * ```
- *
- * If you are using the Engine without the Editor, you have to create the application instance
- * manually.
+ * Application is a subclass of {@link AppBase}, which represents the base functionality for all
+ * PlayCanvas applications. It acts as a convenience class by internally registering all
+ * {@link ComponentSystem}s and {@link ResourceHandler}s implemented in the PlayCanvas Engine. This
+ * makes app setup simple but results in the full engine being included when bundling for your
+ * application.
  */
 class Application extends AppBase {
     /**

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

@@ -1,8 +1,21 @@
 import { Component } from '../component.js';
 
 /**
- * Represents the audio listener in the 3D world, so that 3D positioned audio sources are heard
- * correctly.
+ * The AudioListenerComponent enables an {@link Entity} to represent the point from where
+ * positional {@link SoundComponent}s are heard. This is typically the main camera Entity in your
+ * scene. And typically, you will only have one AudioListenerComponent in your scene.
+ *
+ * You should never need to use the AudioListenerComponent constructor directly. To add a
+ * AudioListenerComponent to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('audiolistener');
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Positional Sound](https://playcanvas.github.io/#/sound/positional)
  *
  * @hideconstructor
  * @category Sound

src/framework/components/camera/component.js

@@ -31,24 +31,31 @@ import { PostEffectQueue } from './post-effect-queue.js';
  */
 
 /**
- * The Camera Component enables an Entity to render the scene. A scene requires at least one
- * enabled camera component to be rendered. Note that multiple camera components can be enabled
- * simultaneously (for split-screen or offscreen rendering, for example).
+ * The CameraComponent enables an {@link Entity} to render the scene. A scene requires at least
+ * one enabled camera component to be rendered. The camera's view direction is along the negative
+ * z-axis of the owner entity.
+ *
+ * Note that multiple camera components can be enabled simultaneously (for split-screen or
+ * offscreen rendering, for example).
+ *
+ * You should never need to use the CameraComponent constructor directly. To add a CameraComponent
+ * to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript
- * // Add a pc.CameraComponent to an entity
  * const entity = new pc.Entity();
  * entity.addComponent('camera', {
  *     nearClip: 1,
  *     farClip: 100,
  *     fov: 55
  * });
+ * ```
  *
- * // Get the pc.CameraComponent on an entity
- * const cameraComponent = entity.camera;
+ * Once the CameraComponent is added to the entity, you can access it via the `camera` property:
+ *
+ * ```javascript
+ * entity.camera.nearClip = 2; // Set the near clip of the camera
  *
- * // Update a property on a camera component
- * entity.camera.nearClip = 2;
+ * console.log(entity.camera.nearClip); // Get the near clip of the camera
  * ```
  *
  * @hideconstructor

src/framework/components/collision/component.js

@@ -15,20 +15,46 @@ const _vec3 = new Vec3();
 const _quat = new Quat();
 
 /**
- * A collision volume. Use this in conjunction with a {@link RigidBodyComponent} to make a
+ * The CollisionComponent enables an {@link Entity} to act as a collision volume. Use it on its own
+ * to define a trigger volume. Or use it in conjunction with a {@link RigidBodyComponent} to make a
  * collision volume that can be simulated using the physics engine.
  *
- * If the {@link Entity} does not have a {@link RigidBodyComponent} then this collision volume will
- * act as a trigger volume. When an entity with a dynamic or kinematic body enters or leaves an
- * entity with a trigger volume, both entities will receive trigger events.
+ * 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.
  *
- * The following table shows all the events that can be fired between two Entities:
+ * You should never need to use the CollisionComponent constructor directly. To add an
+ * CollisionComponent to an {@link Entity}, use {@link Entity#addComponent}:
  *
- * |                                       | Rigid Body (Static)                                                   | Rigid Body (Dynamic or Kinematic)                                     | Trigger Volume                                      |
- * | ------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------- |
- * | **Rigid Body (Static)**               |                                                                       | <ul><li>contact</li><li>collisionstart</li><li>collisionend</li></ul> |                                                     |
- * | **Rigid Body (Dynamic or Kinematic)** | <ul><li>contact</li><li>collisionstart</li><li>collisionend</li></ul> | <ul><li>contact</li><li>collisionstart</li><li>collisionend</li></ul> | <ul><li>triggerenter</li><li>triggerleave</li></ul> |
- * | **Trigger Volume**                    |                                                                       | <ul><li>triggerenter</li><li>triggerleave</li></ul>                   |                                                     |
+ * ```javascript
+ * const entity = 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();
+ * entity.addComponent('collision', {
+ *     type: 'sphere'
+ * });
+ * entity.addComponent('rigidbody', {
+ *     type: 'dynamic'
+ * });
+ * ```
+ *
+ * Once the CollisionComponent is added to the entity, you can access it via the `collision` property:
+ *
+ * ```javascript
+ * entity.collision.type = 'cylinder'; // Set the collision volume to a cylinder
+ *
+ * console.log(entity.collision.type); // Get the collision volume type and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Compound Collision](https://playcanvas.github.io/#/physics/compound-collision)
+ * - [Falling Shapes](https://playcanvas.github.io/#/physics/falling-shapes)
+ * - [Offset Collision](https://playcanvas.github.io/#/physics/offset-collision)
  *
  * @hideconstructor
  * @category Physics

src/framework/components/element/component.js

@@ -45,37 +45,36 @@ const matD = new Mat4();
  * {@link ScreenComponent} ancestor, the ElementComponent will be transformed like any other
  * entity.
  *
- * You should never need to use the ElementComponent constructor. To add an ElementComponent to a
- * {@link Entity}, use {@link Entity#addComponent}:
+ * You should never need to use the ElementComponent constructor directly. To add an
+ * ElementComponent to an {@link Entity}, use {@link Entity#addComponent}:
  *
  * ```javascript
- * // Add an element component to an entity with the default options
  * const entity = pc.Entity();
- * entity.addComponent("element"); // This defaults to a 'group' element
+ * entity.addComponent('element'); // This defaults to a 'group' element
  * ```
  *
  * To create a simple text-based element:
  *
  * ```javascript
- * entity.addComponent("element", {
+ * entity.addComponent('element', {
  *     anchor: new pc.Vec4(0.5, 0.5, 0.5, 0.5), // centered anchor
  *     fontAsset: fontAsset,
  *     fontSize: 128,
  *     pivot: new pc.Vec2(0.5, 0.5),            // centered pivot
- *     text: "Hello World!",
+ *     text: 'Hello World!',
  *     type: pc.ELEMENTTYPE_TEXT
  * });
  * ```
  *
- * Once the ElementComponent is added to the entity, you can set and get any of its properties:
+ * Once the ElementComponent is added to the entity, you can access it via the `element` property:
  *
  * ```javascript
  * entity.element.color = pc.Color.RED; // Set the element's color to red
  *
  * console.log(entity.element.color);   // Get the element's color and print it
  * ```
  *
- * Relevant 'Engine-only' examples:
+ * Relevant Engine API examples:
  *
  * - [Basic text rendering](https://playcanvas.github.io/#/user-interface/text)
  * - [Auto font sizing](https://playcanvas.github.io/#/user-interface/text-auto-font-size)