Improve ScreenComponent API docs (#7622)

* Improve ScreenComponent API docs

* Comma

* Update src/framework/components/screen/component.js

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: willeastcott

src/framework/components/camera/component.js

@@ -51,7 +51,8 @@ import { PostEffectQueue } from './post-effect-queue.js';
  * });
  * ```
  *
- * Once the CameraComponent is added to the entity, you can access it via the `camera` property:
+ * Once the CameraComponent is added to the entity, you can access it via the {@link Entity#camera}
+ * property:
  *
  * ```javascript
  * entity.camera.nearClip = 2; // Set the near clip of the camera

src/framework/components/collision/component.js

@@ -42,7 +42,8 @@ const _quat = new Quat();
  * });
  * ```
  *
- * Once the CollisionComponent is added to the entity, you can access it via the `collision` property:
+ * Once the CollisionComponent is added to the entity, you can access it via the
+ * {@link Entity#collision} property:
  *
  * ```javascript
  * entity.collision.type = 'cylinder'; // Set the collision volume to a cylinder

src/framework/components/element/component.js

@@ -66,7 +66,8 @@ const matD = new Mat4();
  * });
  * ```
  *
- * Once the ElementComponent is added to the entity, you can access it via the `element` property:
+ * Once the ElementComponent is added to the entity, you can access it via the
+ * {@link Entity#element} property:
  *
  * ```javascript
  * entity.element.color = pc.Color.RED; // Set the element's color to red

src/framework/components/gsplat/component.js

@@ -28,7 +28,8 @@ import { Component } from '../component.js';
  * });
  * ```
  *
- * Once the GSplatComponent is added to the entity, you can access it via the `gsplat` property:
+ * Once the GSplatComponent is added to the entity, you can access it via the {@link Entity#gsplat}
+ * property:
  *
  * ```javascript
  * entity.gsplat.customAabb = new pc.BoundingBox(new pc.Vec3(), new pc.Vec3(10, 10, 10));

src/framework/components/light/component.js

@@ -37,7 +37,8 @@ import { properties } from './data.js';
  * });
  * ```
  *
- * Once the LightComponent is added to the entity, you can access it via the `light` property:
+ * Once the LightComponent is added to the entity, you can access it via the {@link Entity#light}
+ * property:
  *
  * ```javascript
  * entity.light.intensity = 3; // Set the intensity of the light

src/framework/components/model/component.js

@@ -39,7 +39,8 @@ import { Component } from '../component.js';
  * });
  * ```
  *
- * Once the ModelComponent is added to the entity, you can access it via the `model` property:
+ * Once the ModelComponent is added to the entity, you can access it via the {@link Entity#model}
+ * property:
  *
  * ```javascript
  * entity.model.type = 'capsule';  // Set the model component's type

src/framework/components/render/component.js

@@ -40,7 +40,8 @@ import { Component } from '../component.js';
  * });
  * ```
  *
- * Once the RenderComponent is added to the entity, you can access it via the `render` property:
+ * Once the RenderComponent is added to the entity, you can access it via the {@link Entity#render}
+ * property:
  *
  * ```javascript
  * entity.render.type = 'capsule';  // Set the render component's type

src/framework/components/rigid-body/component.js

@@ -49,7 +49,8 @@ const _vec3 = new Vec3();
  * });
  * ```
  *
- * Once the RigidBodyComponent is added to the entity, you can access it via the `rigidbody` property:
+ * Once the RigidBodyComponent is added to the entity, you can access it via the
+ * {@link Entity#rigidbody} property:
  *
  * ```javascript
  * entity.rigidbody.mass = 10;

src/framework/components/screen/component.js

@@ -12,8 +12,42 @@ import { Component } from '../component.js';
 const _transform = new Mat4();
 
 /**
- * A ScreenComponent enables the Entity to render child {@link ElementComponent}s using anchors and
- * positions in the ScreenComponent's space.
+ * A ScreenComponent defines a rectangular area where user interfaces can be constructed. Screens
+ * can either be 2D (screen space) or 3D (world space) - see {@link screenSpace}. It is possible to
+ * create an {@link Entity} hierarchy underneath an Entity with a ScreenComponent to create complex
+ * user interfaces using the following components:
+ *
+ * - {@link ButtonComponent}
+ * - {@link ElementComponent}
+ * - {@link LayoutChildComponent}
+ * - {@link LayoutGroupComponent}
+ * - {@link ScrollbarComponent}
+ * - {@link ScrollViewComponent}
+ *
+ * You should never need to use the ScreenComponent constructor directly. To add a ScreenComponent
+ * to an {@link Entity}, use {@link Entity#addComponent}:
+ *
+ * ```javascript
+ * const entity = new pc.Entity();
+ * entity.addComponent('screen', {
+ *     referenceResolution: new pc.Vec2(1280, 720),
+ *     screenSpace: false
+ * });
+ * ```
+ *
+ * Once the ScreenComponent is added to the entity, you can access it via the {@link Entity#screen}
+ * property:
+ *
+ * ```javascript
+ * entity.screen.scaleBlend = 0.6; // Set the screen's scale blend to 0.6
+ *
+ * console.log(entity.screen.scaleBlend); // Get the screen's scale blend and print it
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Screen Space Screen](https://playcanvas.github.io/#/user-interface/text)
+ * - [World Space Screen](https://playcanvas.github.io/#/user-interface/world-ui)
  *
  * @hideconstructor
  * @category User Interface
@@ -157,8 +191,9 @@ class ScreenComponent extends Component {
     }
 
     /**
-     * Sets the width and height of the ScreenComponent. When screenSpace is true the resolution will
-     * always be equal to {@link GraphicsDevice#width} x {@link GraphicsDevice#height}.
+     * Sets the width and height of the ScreenComponent. When {@link screenSpace} is true, the
+     * resolution will always be equal to {@link GraphicsDevice#width} by
+     * {@link GraphicsDevice#height}.
      *
      * @type {Vec2}
      */
@@ -193,9 +228,9 @@ class ScreenComponent extends Component {
 
     /**
      * Sets the resolution that the ScreenComponent is designed for. This is only taken into
-     * account when screenSpace is true and scaleMode is {@link SCALEMODE_BLEND}. If the actual
-     * resolution is different then the ScreenComponent will be scaled according to the scaleBlend
-     * value.
+     * account when {@link screenSpace} is true and {@link scaleMode} is {@link SCALEMODE_BLEND}.
+     * If the actual resolution is different, then the ScreenComponent will be scaled according to
+     * the {@link scaleBlend} value.
      *
      * @type {Vec2}
      */
@@ -226,7 +261,7 @@ class ScreenComponent extends Component {
 
     /**
      * Sets whether the ScreenComponent will render its child {@link ElementComponent}s in screen
-     * space instead of world space. Enable this to create 2D user interfaces.
+     * space instead of world space. Enable this to create 2D user interfaces. Defaults to false.
      *
      * @type {boolean}
      */
@@ -258,7 +293,8 @@ class ScreenComponent extends Component {
 
     /**
      * Sets the scale mode. Can either be {@link SCALEMODE_NONE} or {@link SCALEMODE_BLEND}. See
-     * the description of referenceResolution for more information.
+     * the description of {@link referenceResolution} for more information. Defaults to
+     * {@link SCALEMODE_NONE}.
      *
      * @type {string}
      */
@@ -287,9 +323,10 @@ class ScreenComponent extends Component {
     }
 
     /**
-     * Sets the scale blend. This is a value between 0 and 1 that is used when scaleMode is equal
-     * to {@link SCALEMODE_BLEND}. Scales the ScreenComponent with width as a reference (when value
-     * is 0), the height as a reference (when value is 1) or anything in between.
+     * Sets the scale blend. This is a value between 0 and 1 that is used when {@link scaleMode} is
+     * equal to {@link SCALEMODE_BLEND}. Scales the ScreenComponent with width as a reference (when
+     * value is 0), the height as a reference (when value is 1) or anything in between. Defaults to
+     * 0.5.
      *
      * @type {number}
      */
@@ -317,9 +354,9 @@ class ScreenComponent extends Component {
     }
 
     /**
-     * Sets the priority. Priority determines the order in which Screen components in the same
-     * layer are rendered. Number must be an integer between 0 and 255. Priority is set into the
-     * top 8 bits of the drawOrder property in an element.
+     * Sets the screen's render priority. Priority determines the order in which ScreenComponents
+     * in the same layer are rendered. Number must be an integer between 0 and 255. Priority is set
+     * into the top 8 bits of the {@link ElementComponent#drawOrder} property. Defaults to 0.
      *
      * @type {number}
      */
@@ -337,7 +374,7 @@ class ScreenComponent extends Component {
     }
 
     /**
-     * Gets the priority.
+     * Gets the screen's render priority.
      *
      * @type {number}
      */

src/framework/components/script/component.js

@@ -29,7 +29,9 @@ const toLowerCamelCase = str => str[0].toLowerCase() + str.substring(1);
  * entity.addComponent('script');
  * ```
  *
- * Once the ScriptComponent is added to the entity, you can access it via the `script` property.
+ * Once the ScriptComponent is added to the entity, you can access it via the {@link Entity#script}
+ * property.
+ *
  * Add scripts to the entity by calling the `create` method:
  *
  * ```javascript