Clarify Transform and GlobalTransform documentation (adopted)

crates/bevy_transform/src/bundles.rs

@@ -12,8 +12,10 @@ use crate::prelude::{GlobalTransform, Transform};
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
-/// [`Transform`] is the position of an entity relative to its parent position, or the reference
-/// frame if it doesn't have a parent.
+///
+/// [`Transform`] is the local transform (translation, rotation, scale) of an entity in space.
+/// If the entity has a parent, the local transform is relative to its parent's
+/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.
 ///
 /// [`GlobalTransform`] is the position of an entity relative to the reference frame.
 ///

crates/bevy_transform/src/components/global_transform.rs

@@ -9,33 +9,62 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect};
 #[cfg(all(feature = "bevy-support", feature = "serialize"))]
 use bevy_reflect::{ReflectDeserialize, ReflectSerialize};
 
-/// [`GlobalTransform`] is an affine transformation from entity-local coordinates to worldspace coordinates.
+/// Describes the absolute transform (translation, rotation, scale) of an entity in space,
+/// relative to the main reference frame.
 ///
-/// You cannot directly mutate [`GlobalTransform`]; instead, you change an entity's transform by manipulating
-/// its [`Transform`], which indirectly causes Bevy to update its [`GlobalTransform`].
+/// ## Usage
 ///
-/// * To get the global transform of an entity, you should get its [`GlobalTransform`].
-/// * For transform hierarchies to work correctly, you must have both a [`Transform`] and a [`GlobalTransform`].
-///   * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this.
+/// * To place or move an entity, you should set its [`Transform`].
+/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`],
+///   after [`TransformPropagate`] or [`PostUpdate`] to avoid a 1 frame lag.
+///   * You can use [`compute_transform`] to get the global `translation`, `rotation` and `scale`.
+/// * [`GlobalTransform`] is fully managed by bevy, you cannot mutate it, use
+///   [`Transform`] instead, the [`GlobalTransform`] will be automatically updated with [`TransformPropagate`].
+///   * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee
+///     an entity has both components.
+///
+/// ## `translation`, `rotation` and `scale`
+///
+/// [`GlobalTransform`] represents:
+/// - The position of an entity in space, defined as a `translation` from the origin,
+///   [`Vec3::ZERO`]. The unit doesn't have a predefined meaning, but the convention
+///   is usually to consider `1.0` equivalent to 1 meter.
+/// - The `rotation` of an entity in space, [`Quat::IDENTITY`] representing the rotation
+///   where [`Vec3::Z`] is forward and [`Vec3::Y`] is up.
+/// - The `scale` of an entity, `1.0` representing the "size values" of the entity
+///   matching the main reference frame coordinates.
+///   It can be seen as a ratio of the main reference frame length unit to
+///   the entity's length unit.
+///   For example if the scale is `1.0` for a `Mesh`, its vertices position attribute
+///   have the same unit than the values used inside `translation`.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
-/// [`Transform`] transforms an entity relative to its parent's reference frame, or relative to world space coordinates,
-/// if it doesn't have a [`Parent`](bevy_hierarchy::Parent).
+/// [`Transform`] is the local transform of an entity in space relative to its parent transform,
+/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`].
 ///
-/// [`GlobalTransform`] is managed by Bevy; it is computed by successively applying the [`Transform`] of each ancestor
-/// entity which has a Transform. This is done automatically by Bevy-internal systems in the system set
-/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate).
+/// [`GlobalTransform`] is the absolute transform of an entity in space, relative to the main reference frame.
 ///
-/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you
-/// update the [`Transform`] of an entity in this schedule or after, you will notice a 1 frame lag
-/// before the [`GlobalTransform`] is updated.
+/// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set
+/// [`TransformPropagate`].
+/// Those systems run during [`PostUpdate`].
+/// If you update the [`Transform`] of an entity in this schedule or after,
+/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.
 ///
 /// # Examples
 ///
-/// - [`transform`][transform_example]
+/// - The [`transform example`], or the other examples in the [`transforms folder`],
+///   to learn how to use the [`Transform`] of an entity.
+/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy.
 ///
-/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`compute_transform`]: GlobalTransform::compute_transform
+/// [`TransformBundle`]: crate::TransformBundle
+/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate
+/// [`PostUpdate`]: bevy_app::PostUpdate
+/// [`Parent`]: bevy_hierarchy::Parent
+/// [`transform example`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`transforms folder`]: https://github.com/bevyengine/bevy/tree/latest/examples/transforms
+/// [`parenting example`]: https://bevyengine.org/examples/3d/parenting/
 #[derive(Debug, PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(

crates/bevy_transform/src/components/transform.rs

@@ -6,33 +6,73 @@ use bevy_math::{Affine3A, Dir3, Isometry3d, Mat3, Mat4, Quat, Vec3};
 use bevy_reflect::prelude::*;
 use std::ops::Mul;
 
-/// Describe the position of an entity. If the entity has a parent, the position is relative
-/// to its parent position.
+/// Describes the local transform (translation, rotation, scale) of an entity in space.
+/// If the entity has a parent, the local transform is relative to its parent's
+/// [`GlobalTransform`], otherwise, it's relative to the main reference frame.
+///
+/// ## Usage
 ///
 /// * To place or move an entity, you should set its [`Transform`].
-/// * To get the global transform of an entity, you should get its [`GlobalTransform`].
+/// * To get the absolute transform of an entity, you should get its [`GlobalTransform`],
+///   after [`TransformPropagate`] or [`PostUpdate`] to avoid a 1 frame lag.
 /// * To be displayed, an entity must have both a [`Transform`] and a [`GlobalTransform`].
-///   * You may use the [`TransformBundle`](crate::bundles::TransformBundle) to guarantee this.
+///   * You may use the [`TransformBundle`] to guarantee this.
+///
+/// ## `translation`, `rotation` and `scale`
+///
+/// If the entity has no parent, [`Transform`] is relative to the main reference frame:
+/// - The position of an entity in space, defined as a `translation` from the origin,
+///   [`Vec3::ZERO`]. The length unit doesn't have a predefined meaning, but the convention
+///   is usually to consider `1.0` equivalent to 1 meter.
+/// - The `rotation` of an entity in space, [`Quat::IDENTITY`] representing the rotation
+///   where [`Vec3::Z`] is forward and [`Vec3::Y`] is up.
+/// - The `scale` of an entity, `1.0` representing the "size values" of the entity
+///   matching the main reference frame coordinates.
+///   It can be seen as a ratio of the main reference frame length unit to
+///   the entity's length unit.
+///   For example if the scale is `1.0` for a `Mesh`, its vertex position attributes
+///   have the same unit than the values used inside `translation`.
+///
+/// If the entity has a parent:
+/// - The `translation` is relative to the parent's [`GlobalTransform`], it is
+///   added to it.
+///   Another way of seeing it is that the `translation`'s origin is the
+///   parent global position.
+/// - The `rotation` is relative to the parent's [`GlobalTransform`], it is multiplied
+///   by it.
+///   Another way of seeing it is that [`Quat::IDENTITY`] represents the rotation
+///   where the parent's global forward axis is forward and the parent's global up axis is up.
+/// - The `scale` is relative to the parent's [`GlobalTransform`], it is multiplied
+///   by it.
+///   Another way of seeing it is to consider the parent has its own length unit
+///   used by the child.
 ///
 /// ## [`Transform`] and [`GlobalTransform`]
 ///
-/// [`Transform`] is the position of an entity relative to its parent position, or the reference
-/// frame if it doesn't have a [`Parent`](bevy_hierarchy::Parent).
+/// [`Transform`] is the local transform of an entity in space relative to its parent transform,
+/// or the global transform relative to the main reference frame if it doesn't have a [`Parent`].
 ///
-/// [`GlobalTransform`] is the position of an entity relative to the reference frame.
+/// [`GlobalTransform`] is the absolute transform of an entity in space, relative to the main reference frame.
 ///
 /// [`GlobalTransform`] is updated from [`Transform`] by systems in the system set
-/// [`TransformPropagate`](crate::TransformSystem::TransformPropagate).
-///
-/// This system runs during [`PostUpdate`](bevy_app::PostUpdate). If you
-/// update the [`Transform`] of an entity during this set or after, you will notice a 1 frame lag
-/// before the [`GlobalTransform`] is updated.
+/// [`TransformPropagate`].
+/// Those systems run during [`PostUpdate`].
+/// If you update the [`Transform`] of an entity in this schedule or after,
+/// you may notice a 1 frame lag before the [`GlobalTransform`] is updated.
 ///
 /// # Examples
 ///
-/// - [`transform`][transform_example]
+/// - The [`transform example`], or the other examples in the [`transforms folder`],
+///   to learn how to use the [`Transform`] of an entity.
+/// - The [`parenting example`], to learn how [`Transform`] behaves in a hierarchy.
 ///
-/// [transform_example]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`TransformBundle`]: crate::bundles::TransformBundle
+/// [`TransformPropagate`]: crate::TransformSystem::TransformPropagate
+/// [`PostUpdate`]: bevy_app::PostUpdate
+/// [`Parent`]: bevy_hierarchy::Parent
+/// [`transform example`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs
+/// [`transforms folder`]: https://github.com/bevyengine/bevy/tree/latest/examples/transforms
+/// [`parenting example`]: https://bevyengine.org/examples/3d-rendering/parenting/
 #[derive(Debug, PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(