Improve typings and docs for XrPlane (#6708)

* Improve typing for XrPlane#points

* Tweak docs for XrPlane#label

* Improve class description

* Improve orientation docs

* Tweak example source

* Correct XrTrackedImage construction docs

* Tighten type for XrPlane#orientation

src/framework/xr/xr-plane.js

@@ -5,8 +5,10 @@ import { Vec3 } from '../../core/math/vec3.js';
 let ids = 0;
 
 /**
- * Detected Plane instance that provides position, rotation, polygon points and its semantic label.
- * Plane data is subject to change during its lifetime.
+ * Represents a detected plane in the real world, providing its position, rotation, polygon points,
+ * and semantic label. The plane data may change over time as the system updates its understanding
+ * of the environment. Instances of this class are created and managed by the
+ * {@link XrPlaneDetection} system.
  *
  * @category XR
  */
@@ -59,7 +61,7 @@ class XrPlane extends EventHandler {
     _lastChangedTime;
 
     /**
-     * @type {string}
+     * @type {"horizontal"|"vertical"|null}
      * @private
      */
     _orientation;
@@ -150,24 +152,36 @@ class XrPlane extends EventHandler {
     }
 
     /**
-     * Plane's specific orientation (horizontal or vertical) or null if orientation is anything else.
+     * Gets the plane's specific orientation. This can be "horizontal" for planes that are parallel
+     * to the ground, "vertical" for planes that are perpendicular to the ground, or `null` if the
+     * orientation is different or unknown.
      *
-     * @type {string|null}
+     * @type {"horizontal"|"vertical"|null}
+     * @example
+     * if (plane.orientation === 'horizontal') {
+     *     console.log('This plane is horizontal.');
+     * } else if (plane.orientation === 'vertical') {
+     *     console.log('This plane is vertical.');
+     * } else {
+     *     console.log('Orientation of this plane is unknown or different.');
+     * }
      */
     get orientation() {
         return this._orientation;
     }
 
     /**
-     * Array of DOMPointReadOnly objects. DOMPointReadOnly is an object with `x y z` properties
-     * that defines a local point of a plane's polygon.
+     * Gets the array of points that define the polygon of the plane in its local coordinate space.
+     * Each point is represented as a `DOMPointReadOnly` object with `x`, `y`, and `z` properties.
+     * These points can be transformed to world coordinates using the plane's position and
+     * rotation.
      *
-     * @type {object[]}
+     * @type {DOMPointReadOnly[]}
      * @example
      * // prepare reusable objects
+     * const transform = new pc.Mat4();
      * const vecA = new pc.Vec3();
      * const vecB = new pc.Vec3();
-     * const color = new pc.Color(1, 1, 1);
      *
      * // update Mat4 to plane position and rotation
      * transform.setTRS(plane.getPosition(), plane.getRotation(), pc.Vec3.ONE);
@@ -177,23 +191,30 @@ class XrPlane extends EventHandler {
      *     vecA.copy(plane.points[i]);
      *     vecB.copy(plane.points[(i + 1) % plane.points.length]);
      *
-     *     // transform from planes local to world coords
+     *     // transform points to world space
      *     transform.transformPoint(vecA, vecA);
      *     transform.transformPoint(vecB, vecB);
      *
      *     // render line
-     *     app.drawLine(vecA, vecB, color);
+     *     app.drawLine(vecA, vecB, pc.Color.WHITE);
      * }
      */
     get points() {
         return this._xrPlane.polygon;
     }
 
     /**
-     * Semantic Label of a plane that is provided by underlying system.
-     * Current list includes (but not limited to): https://github.com/immersive-web/semantic-labels/blob/master/labels.json
+     * Gets the semantic label of the plane provided by the underlying system. The label describes
+     * the type of surface the plane represents, such as "floor", "wall", "ceiling", etc. The list
+     * of possible labels can be found in the [semantic labels repository](https://github.com/immersive-web/semantic-labels).
      *
      * @type {string}
+     * @example
+     * if (plane.label === 'floor') {
+     *     console.log('This plane represents the floor.');
+     * } else if (plane.label === 'wall') {
+     *     console.log('This plane represents a wall.');
+     * }
      */
     get label() {
         return this._xrPlane.semanticLabel || '';

src/framework/xr/xr-tracked-image.js

@@ -93,9 +93,7 @@ class XrTrackedImage extends EventHandler {
     _rotation = new Quat();
 
     /**
-     * The tracked image interface that is created by the Image Tracking system and is provided as
-     * a list from {@link XrImageTracking#images}. It contains information about the tracking state
-     * as well as the position and rotation of the tracked image.
+     * Create a new XrTrackedImage instance.
      *
      * @param {HTMLCanvasElement|HTMLImageElement|SVGImageElement|HTMLVideoElement|Blob|ImageData|ImageBitmap} image - Image
      * that is matching the real world image as closely as possible. Resolution of images should be