Merge pull request #776 from fpdotmonkey/document-basis-a-b-c

Document why `Basis` columns are `a`, `b`, and `c`

Author: Bromeon

godot-core/src/builtin/basis.rs

@@ -23,6 +23,12 @@ use std::ops::{Mul, MulAssign};
 ///
 /// The basis vectors are the columns of the matrix, whereas the [`rows`](Self::rows) field represents
 /// the row vectors.
+///
+/// Note that the names of the column vectors here are `a`, `b`, and `c`, which differs from Godot's convention of `x`, `y`, and `z`.  This is
+/// because columns are the basis vectors of the transform, while rows represent the X/Y/Z coordinates of each vector. Although basis vectors are
+/// the _transformed_ unit vectors of X/Y/Z axes, they have no direct relation to those axes in the _transformed_ coordinate system. Thus, an
+/// independent notion of a, b, c does not suggest such a relation.  Furthermore, there are sometimes expressions such as `x.x`, `x.y`, `y.x`
+/// etc. They are typically hard to read and error-prone to write. Having `a.x`, `a.y`, `b.x` makes things more understandable.
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]
@@ -457,7 +463,7 @@ impl Basis {
 
     /// Returns the first column of the matrix,
     ///
-    /// _Godot equivalent: `Basis.x`_
+    /// _Godot equivalent: `Basis.x`_, see [`Basis`] for why it's changed
     #[doc(alias = "x")]
     #[must_use]
     pub fn col_a(&self) -> Vector3 {
@@ -473,7 +479,7 @@ impl Basis {
 
     /// Returns the second column of the matrix,
     ///
-    /// _Godot equivalent: `Basis.y`_
+    /// _Godot equivalent: `Basis.y`_, see [`Basis`] for why it's changed
     #[doc(alias = "y")]
     #[must_use]
     pub fn col_b(&self) -> Vector3 {
@@ -489,7 +495,7 @@ impl Basis {
 
     /// Returns the third column of the matrix,
     ///
-    /// _Godot equivalent: `Basis.z`_
+    /// _Godot equivalent: `Basis.z`_, see [`Basis`] for why it's changed
     #[doc(alias = "z")]
     #[must_use]
     pub fn col_c(&self) -> Vector3 {

godot-core/src/builtin/transform2d.rs

@@ -31,12 +31,12 @@ use std::ops::{Mul, MulAssign};
 pub struct Transform2D {
     /// The first basis vector.
     ///
-    /// This is equivalent to the `x` field from godot.
+    /// _Godot equivalent: `Transform2D.x`_, see [`Basis`][crate::builtin::Basis] for why it's changed
     pub a: Vector2,
 
     /// The second basis vector.
     ///
-    /// This is equivalent to the `y` field from godot.
+    /// _Godot equivalent: `Transform2D.y`_, see [`Basis`][crate::builtin::Basis] for why it's changed
     pub b: Vector2,
 
     /// The origin of the transform. The coordinate space defined by this transform
@@ -71,7 +71,8 @@ impl Transform2D {
 
     /// Create a new `Transform2D` with the given column vectors.
     ///
-    /// _Godot equivalent: `Transform2D(Vector2 x_axis, Vector2 y_axis, Vector2 origin)`_
+    /// _Godot equivalent: `Transform2D(Vector2 x_axis, Vector2 y_axis, Vector2 origin)`_, see [`Basis`][crate::builtin::Basis] for why it's
+    /// changed
     pub const fn from_cols(a: Vector2, b: Vector2, origin: Vector2) -> Self {
         Self { a, b, origin }
     }
@@ -291,6 +292,9 @@ impl Transform2D {
 }
 
 impl Display for Transform2D {
+    /// Formats the value with the given formatter.  [Read more](https://doc.rust-lang.org/1.79.0/core/fmt/trait.Display.html#tymethod.fmt)
+    ///
+    /// The output is similar to Godot's, but calls the columns a/b instead of X/Y.  See [`Basis`][crate::builtin::Basis] for why.
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         // Godot output:
         // [X: (1, 2), Y: (3, 4), O: (5, 6)]

godot-core/src/builtin/transform3d.rs

@@ -69,7 +69,8 @@ impl Transform3D {
 
     /// Create a new transform from 4 matrix-columns.
     ///
-    /// _Godot equivalent: `Transform3D(Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin)`_
+    /// _Godot equivalent: `Transform3D(Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin)`_, see [`Basis`][crate::builtin::Basis]
+    /// for why it's changed
     pub const fn from_cols(a: Vector3, b: Vector3, c: Vector3, origin: Vector3) -> Self {
         Self {
             basis: Basis::from_cols(a, b, c),
@@ -265,10 +266,13 @@ impl Transform3D {
 }
 
 impl Display for Transform3D {
+    /// Formats the value with the given formatter.  [Read more](https://doc.rust-lang.org/1.79.0/core/fmt/trait.Display.html#tymethod.fmt)
+    ///
+    /// The output is similar to Godot's, but calls the columns a/b/c instead of X/Y/Z.  See [`Basis`][crate::builtin::Basis] for why.
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         // Godot output:
         // [X: (1, 2, 3), Y: (4, 5, 6), Z: (7, 8, 9), O: (10, 11, 12)]
-        // Where X,Y,O are the columns
+        // Where X,Y,Z,O are the columns
         let [a, b, c] = self.basis.to_cols();
         let o = self.origin;