From 7f59d67ae89ac0adeb9fcf7083d1b63a050cb2aa Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Sun, 27 Apr 2025 15:23:48 +0100
Subject: [PATCH] Improve Gizmo API docs

---
 src/extras/gizmo/rotate-gizmo.js    | 36 ++++++++++++++++++++++++++---
 src/extras/gizmo/scale-gizmo.js     | 36 ++++++++++++++++++++++++++---
 src/extras/gizmo/translate-gizmo.js | 36 ++++++++++++++++++++++++++---
 3 files changed, 99 insertions(+), 9 deletions(-)

diff --git a/src/extras/gizmo/rotate-gizmo.js b/src/extras/gizmo/rotate-gizmo.js
index ad4e2a62709..e268bf83ae9 100644
--- a/src/extras/gizmo/rotate-gizmo.js
+++ b/src/extras/gizmo/rotate-gizmo.js
@@ -29,7 +29,36 @@ const FACING_THRESHOLD = 0.9;
 const GUIDE_ANGLE_COLOR = new Color(0, 0, 0, 0.3);
 
 /**
- * Rotation gizmo.
+ * The RotateGizmo provides interactive 3D manipulation handles for rotating/reorienting
+ * {@link Entity}s in a {@link Scene}. It creates a visual widget with a draggable ring for each
+ * axis of rotation, plus a fourth ring for rotation in the camera's view plane, allowing precise
+ * control over object orientation through direct manipulation. The gizmo's visual appearance can
+ * be customized away from the defaults as required.
+ *
+ * Note that the gizmo can be driven by both mouse+keyboard and touch input.
+ *
+ * ```javascript
+ * // Create a layer for rendering all gizmos
+ * const gizmoLayer = pc.Gizmo.createLayer(app);
+ *
+ * // Create a rotate gizmo
+ * const gizmo = new pc.RotateGizmo(cameraComponent, gizmoLayer);
+ *
+ * // Create an entity to attach the gizmo to
+ * const entity = new pc.Entity();
+ * entity.addComponent('render', {
+ *     type: 'box'
+ * });
+ * app.root.addChild(entity);
+ *
+ * // Attach the gizmo to the entity
+ * gizmo.attach([entity]);
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Rotate Gizmo](https://playcanvas.github.io/#/gizmos/transform-rotate)
+ * - [Editor](https://playcanvas.github.io/#/misc/editor)
  *
  * @category Gizmo
  */
@@ -142,10 +171,11 @@ class RotateGizmo extends TransformGizmo {
     orbitRotation = false;
 
     /**
-     * Creates a new RotateGizmo object.
+     * Creates a new RotateGizmo object. Use {@link Gizmo.createLayer} to create the layer
+     * required to display the gizmo.
      *
      * @param {CameraComponent} camera - The camera component.
-     * @param {Layer} layer - The render layer.
+     * @param {Layer} layer - The layer responsible for rendering the gizmo.
      * @example
      * const gizmo = new pc.RotateGizmo(camera, layer);
      */
diff --git a/src/extras/gizmo/scale-gizmo.js b/src/extras/gizmo/scale-gizmo.js
index 8ca7d9298aa..6dbc9b5c507 100644
--- a/src/extras/gizmo/scale-gizmo.js
+++ b/src/extras/gizmo/scale-gizmo.js
@@ -23,7 +23,36 @@ const tmpQ1 = new Quat();
 const GLANCE_EPSILON = 0.98;
 
 /**
- * Scaling gizmo.
+ * The ScaleGizmo provides interactive 3D manipulation handles for scaling/resizing
+ * {@link Entity}s in a {@link Scene}. It creates a visual widget with box-tipped lines along the
+ * X, Y and Z axes, planes at their intersections, and a center box, allowing precise control over
+ * object scaling through direct manipulation. The gizmo's visual appearance can be customized
+ * away from the defaults as required.
+ *
+ * Note that the gizmo can be driven by both mouse+keyboard and touch input.
+ *
+ * ```javascript
+ * // Create a layer for rendering all gizmos
+ * const gizmoLayer = pc.Gizmo.createLayer(app);
+ *
+ * // Create a scale gizmo
+ * const gizmo = new pc.ScaleGizmo(cameraComponent, gizmoLayer);
+ *
+ * // Create an entity to attach the gizmo to
+ * const entity = new pc.Entity();
+ * entity.addComponent('render', {
+ *     type: 'box'
+ * });
+ * app.root.addChild(entity);
+ *
+ * // Attach the gizmo to the entity
+ * gizmo.attach([entity]);
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Scale Gizmo](https://playcanvas.github.io/#/gizmos/transform-scale)
+ * - [Editor](https://playcanvas.github.io/#/misc/editor)
  *
  * @category Gizmo
  */
@@ -124,10 +153,11 @@ class ScaleGizmo extends TransformGizmo {
     lowerBoundScale = new Vec3(-Infinity, -Infinity, -Infinity);
 
     /**
-     * Creates a new ScaleGizmo object.
+     * Creates a new ScaleGizmo object. Use {@link Gizmo.createLayer} to create the layer
+     * required to display the gizmo.
      *
      * @param {CameraComponent} camera - The camera component.
-     * @param {Layer} layer - The render layer.
+     * @param {Layer} layer - The layer responsible for rendering the gizmo.
      * @example
      * const gizmo = new pc.ScaleGizmo(camera, layer);
      */
diff --git a/src/extras/gizmo/translate-gizmo.js b/src/extras/gizmo/translate-gizmo.js
index 4d6d592cc56..b3702f634e7 100644
--- a/src/extras/gizmo/translate-gizmo.js
+++ b/src/extras/gizmo/translate-gizmo.js
@@ -29,7 +29,36 @@ const tmpQ1 = new Quat();
 const GLANCE_EPSILON = 0.98;
 
 /**
- * Translation gizmo.
+ * The TranslateGizmo provides interactive 3D manipulation handles for translating/moving
+ * {@link Entity}s in a {@link Scene}. It creates a visual widget with arrows along the X, Y
+ * and Z axes, planes at their intersections, and a center sphere, allowing precise control over
+ * object positioning through direct manipulation. The gizmo's visual appearance can be customized
+ * away from the defaults as required.
+ *
+ * Note that the gizmo can be driven by both mouse+keyboard and touch input.
+ *
+ * ```javascript
+ * // Create a layer for rendering all gizmos
+ * const gizmoLayer = pc.Gizmo.createLayer(app);
+ *
+ * // Create a translate gizmo
+ * const gizmo = new pc.TranslateGizmo(cameraComponent, gizmoLayer);
+ *
+ * // Create an entity to attach the gizmo to
+ * const entity = new pc.Entity();
+ * entity.addComponent('render', {
+ *     type: 'box'
+ * });
+ * app.root.addChild(entity);
+ *
+ * // Attach the gizmo to the entity
+ * gizmo.attach([entity]);
+ * ```
+ *
+ * Relevant Engine API examples:
+ *
+ * - [Translate Gizmo](https://playcanvas.github.io/#/gizmos/transform-translate)
+ * - [Editor](https://playcanvas.github.io/#/misc/editor)
  *
  * @category Gizmo
  */
@@ -121,10 +150,11 @@ class TranslateGizmo extends TransformGizmo {
     flipShapes = true;
 
     /**
-     * Creates a new TranslateGizmo object.
+     * Creates a new TranslateGizmo object. Use {@link Gizmo.createLayer} to create the layer
+     * required to display the gizmo.
      *
      * @param {CameraComponent} camera - The camera component.
-     * @param {Layer} layer - The render layer.
+     * @param {Layer} layer - The layer responsible for rendering the gizmo.
      * @example
      * const gizmo = new pc.TranslateGizmo(camera, layer);
      */