Document why Basis columns are a, b, and c

Why Basis doesn't follow Godot's column name convention came up in
Discord, and the reasoning was fairly buried in code reviews and commits
in other projects, so I'm sharing the knowledge with API users.

The explanation here is lifted directly from
godot-rust/gdnative@16aa18e

Author: fpdotmonkey

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;