From a8c62c592870944555810ad232d87c6ce17098df Mon Sep 17 00:00:00 2001
From: kleonc <9283098+kleonc@users.noreply.github.com>
Date: Mon, 16 Oct 2023 21:26:25 +0200
Subject: [PATCH] Clarify docs for operators performing `xform_inv`

---
 doc/classes/AABB.xml               | 4 +++-
 doc/classes/PackedVector2Array.xml | 4 +++-
 doc/classes/PackedVector3Array.xml | 4 +++-
 doc/classes/Plane.xml              | 1 +
 doc/classes/Rect2.xml              | 4 +++-
 doc/classes/Transform2D.xml        | 8 +++++---
 doc/classes/Transform3D.xml        | 4 ++--
 doc/classes/Vector2.xml            | 4 +++-
 doc/classes/Vector3.xml            | 9 +++++++--
 doc/classes/Vector4.xml            | 3 ++-
 10 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml
index a803e4f106b..c1c637d2d66 100644
--- a/doc/classes/AABB.xml
+++ b/doc/classes/AABB.xml
@@ -245,7 +245,9 @@
 			<return type="AABB" />
 			<param index="0" name="right" type="Transform3D" />
 			<description>
-				Inversely transforms (multiplies) the [AABB] by the given [Transform3D] transformation matrix.
+				Inversely transforms (multiplies) the [AABB] by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]aabb * transform[/code] is equivalent to [code]transform.inverse() * aabb[/code]. See [method Transform3D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * aabb[/code] can be used instead. See [method Transform3D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator ==">
diff --git a/doc/classes/PackedVector2Array.xml b/doc/classes/PackedVector2Array.xml
index 9f8671f076e..0e5bb12d028 100644
--- a/doc/classes/PackedVector2Array.xml
+++ b/doc/classes/PackedVector2Array.xml
@@ -204,7 +204,9 @@
 			<return type="PackedVector2Array" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Transforms (multiplies) all vectors in the array by the [Transform2D] matrix.
+				Returns a new [PackedVector2Array] with all vectors in this array inversely transformed (multiplied) by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]array * transform[/code] is equivalent to [code]transform.inverse() * array[/code]. See [method Transform2D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * array[/code] can be used instead. See [method Transform2D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator +">
diff --git a/doc/classes/PackedVector3Array.xml b/doc/classes/PackedVector3Array.xml
index 54f65a619b2..ce7ae4f3965 100644
--- a/doc/classes/PackedVector3Array.xml
+++ b/doc/classes/PackedVector3Array.xml
@@ -203,7 +203,9 @@
 			<return type="PackedVector3Array" />
 			<param index="0" name="right" type="Transform3D" />
 			<description>
-				Transforms (multiplies) all vectors in the array by the [Transform3D] matrix.
+				Returns a new [PackedVector3Array] with all vectors in this array inversely transformed (multiplied) by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]array * transform[/code] is equivalent to [code]transform.inverse() * array[/code]. See [method Transform3D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * array[/code] can be used instead. See [method Transform3D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator +">
diff --git a/doc/classes/Plane.xml b/doc/classes/Plane.xml
index a0da82d1d64..254557b986f 100644
--- a/doc/classes/Plane.xml
+++ b/doc/classes/Plane.xml
@@ -193,6 +193,7 @@
 			<param index="0" name="right" type="Transform3D" />
 			<description>
 				Inversely transforms (multiplies) the [Plane] by the given [Transform3D] transformation matrix.
+				[code]plane * transform[/code] is equivalent to [code]transform.affine_inverse() * plane[/code]. See [method Transform3D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator ==">
diff --git a/doc/classes/Rect2.xml b/doc/classes/Rect2.xml
index 4f17e3cf2de..0471d73749a 100644
--- a/doc/classes/Rect2.xml
+++ b/doc/classes/Rect2.xml
@@ -237,7 +237,9 @@
 			<return type="Rect2" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Inversely transforms (multiplies) the [Rect2] by the given [Transform2D] transformation matrix.
+				Inversely transforms (multiplies) the [Rect2] by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]rect * transform[/code] is equivalent to [code]transform.inverse() * rect[/code]. See [method Transform2D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * rect[/code] can be used instead. See [method Transform2D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator ==">
diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml
index abb81b95cbb..1611af4226f 100644
--- a/doc/classes/Transform2D.xml
+++ b/doc/classes/Transform2D.xml
@@ -59,7 +59,7 @@
 		<method name="affine_inverse" qualifiers="const">
 			<return type="Transform2D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation.
+				Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant).
 			</description>
 		</method>
 		<method name="basis_xform" qualifiers="const">
@@ -74,8 +74,10 @@
 			<return type="Vector2" />
 			<param index="0" name="v" type="Vector2" />
 			<description>
-				Returns a vector transformed (multiplied) by the inverse basis matrix.
+				Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
 				This method does not account for translation (the origin vector).
+				[code]transform.basis_xform_inv(vector)[/code] is equivalent to [code]transform.inverse().basis_xform(vector)[/code]. See [method inverse].
+				For non-orthonormal transforms (e.g. with scaling) use [code]transform.affine_inverse().basis_xform(vector)[/code] instead. See [method affine_inverse].
 			</description>
 		</method>
 		<method name="determinant" qualifiers="const">
@@ -120,7 +122,7 @@
 		<method name="inverse" qualifiers="const">
 			<return type="Transform2D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use [method affine_inverse] for transforms with scaling).
+				Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling).
 			</description>
 		</method>
 		<method name="is_conformal" qualifiers="const">
diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml
index c96be5124ee..c0331855598 100644
--- a/doc/classes/Transform3D.xml
+++ b/doc/classes/Transform3D.xml
@@ -59,7 +59,7 @@
 		<method name="affine_inverse" qualifiers="const">
 			<return type="Transform3D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation.
+				Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant).
 			</description>
 		</method>
 		<method name="interpolate_with" qualifiers="const">
@@ -73,7 +73,7 @@
 		<method name="inverse" qualifiers="const">
 			<return type="Transform3D" />
 			<description>
-				Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use [method affine_inverse] for transforms with scaling).
+				Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling).
 			</description>
 		</method>
 		<method name="is_equal_approx" qualifiers="const">
diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index fdaaf239f86..3fa7bb46fc2 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -419,7 +419,9 @@
 			<return type="Vector2" />
 			<param index="0" name="right" type="Transform2D" />
 			<description>
-				Inversely transforms (multiplies) the [Vector2] by the given [Transform2D] transformation matrix.
+				Inversely transforms (multiplies) the [Vector2] by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]vector * transform[/code] is equivalent to [code]transform.inverse() * vector[/code]. See [method Transform2D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * vector[/code] can be used instead. See [method Transform2D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator *">
diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml
index 92fbdf68506..77c73914106 100644
--- a/doc/classes/Vector3.xml
+++ b/doc/classes/Vector3.xml
@@ -442,7 +442,9 @@
 			<return type="Vector3" />
 			<param index="0" name="right" type="Basis" />
 			<description>
-				Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix.
+				Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]vector * basis[/code] is equivalent to [code]basis.transposed() * vector[/code]. See [method Basis.transposed].
+				For transforming by inverse of a non-orthonormal basis [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse].
 			</description>
 		</operator>
 		<operator name="operator *">
@@ -450,13 +452,16 @@
 			<param index="0" name="right" type="Quaternion" />
 			<description>
 				Inversely transforms (multiplies) the [Vector3] by the given [Quaternion].
+				[code]vector * quaternion[/code] is equivalent to [code]quaternion.inverse() * vector[/code]. See [method Quaternion.inverse].
 			</description>
 		</operator>
 		<operator name="operator *">
 			<return type="Vector3" />
 			<param index="0" name="right" type="Transform3D" />
 			<description>
-				Inversely transforms (multiplies) the [Vector3] by the given [Transform3D] transformation matrix.
+				Inversely transforms (multiplies) the [Vector3] by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
+				[code]vector * transform[/code] is equivalent to [code]transform.inverse() * vector[/code]. See [method Transform3D.inverse].
+				For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * vector[/code] can be used instead. See [method Transform3D.affine_inverse].
 			</description>
 		</operator>
 		<operator name="operator *">
diff --git a/doc/classes/Vector4.xml b/doc/classes/Vector4.xml
index e5ad5631e83..c5503a93577 100644
--- a/doc/classes/Vector4.xml
+++ b/doc/classes/Vector4.xml
@@ -280,7 +280,8 @@
 			<return type="Vector4" />
 			<param index="0" name="right" type="Projection" />
 			<description>
-				Inversely transforms (multiplies) the [Vector4] by the given [Projection] matrix.
+				Transforms (multiplies) the [Vector4] by the transpose of the given [Projection] matrix.
+				For transforming by inverse of a projection [code]projection.inverse() * vector[/code] can be used instead. See [method Projection.inverse].
 			</description>
 		</operator>
 		<operator name="operator *">