From 532f3cb603bed2d6c89894654ddd93eab3d4039e Mon Sep 17 00:00:00 2001 From: Federico Rinaldi Date: Sun, 3 Sep 2023 01:44:12 +0200 Subject: [PATCH] Improve `SpatialBundle` docs (#9673) # Objective This PR aims to fix a handful of problems with the `SpatialBundle` docs: The docs describe the role of the single components of the bundle, overshadowing the purpose of `SpatialBundle` itself. Also, those items may be added, removed or changed over time, as it happened with #9497, requiring a higher maintenance effort, which will often result in errors, as it happened. ## Solution Just describe the role of `SpatialBundle` and of the transform and visibility concepts, without mentioning the specific component types. Since the bundle has public fields, the reader can easily click them and read the documentation if they need to know more. I removed the mention of numbers of components since they were four, now they are five, and who knows how many they will be in the future. In this process, I removed the bullet points, which are no longer needed, and were contextually wrong in the first place, since they were meant to list the components, but ended up describing use-cases and requirements for hierarchies. --------- Co-authored-by: Alice Cecile --- crates/bevy_render/src/spatial_bundle.rs | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/crates/bevy_render/src/spatial_bundle.rs b/crates/bevy_render/src/spatial_bundle.rs index 5287c38804..27dba5c215 100644 --- a/crates/bevy_render/src/spatial_bundle.rs +++ b/crates/bevy_render/src/spatial_bundle.rs @@ -3,16 +3,18 @@ use bevy_transform::prelude::{GlobalTransform, Transform}; use crate::view::{InheritedVisibility, ViewVisibility, Visibility}; -/// A [`Bundle`] with the following [`Component`](bevy_ecs::component::Component)s: -/// * [`Visibility`], and [`InheritedVisibility`], which describe the visibility of an entity -/// * [`Transform`] and [`GlobalTransform`], which describe the position of an entity +/// A [`Bundle`] that allows the correct positional rendering of an entity. /// -/// * To show or hide an entity, you should set its [`Visibility`]. -/// * To get the computed visibility of an entity, you should get its [`InheritedVisibility`] or [`ViewVisibility`] components. -/// * To place or move an entity, you should set its [`Transform`]. -/// * To get the global transform of an entity, you should get its [`GlobalTransform`]. -/// * For hierarchies to work correctly, you must have all four components. -/// * You may use the [`SpatialBundle`] to guarantee this. +/// It consists of transform components, +/// controlling position, rotation and scale of the entity, +/// but also visibility components, +/// which determine whether the entity is visible or not. +/// +/// Parent-child hierarchies of entities must contain +/// all the [`Component`]s in this `Bundle` +/// to be rendered correctly. +/// +/// [`Component`]: bevy_ecs::component::Component #[derive(Bundle, Debug, Default)] pub struct SpatialBundle { /// The visibility of the entity.