Merge pull request #83461 from kleonc/docs-multiplication-operators-doing-xform_inv

Clarify docs for operators performing `xform_inv`

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 ==">

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 +">

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 +">

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 ==">

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 ==">

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">

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">

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 *">

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 *">

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 *">