From bb5d2dd1b6df9d89e6fd6f71c68b37f01c648f09 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 16 Feb 2025 14:08:01 -0800 Subject: [PATCH 1/4] Improve docs for ChildOf and Children --- crates/bevy_ecs/src/hierarchy.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/bevy_ecs/src/hierarchy.rs b/crates/bevy_ecs/src/hierarchy.rs index 6c8ee9f31b9b0..f2ddfa3b6250e 100644 --- a/crates/bevy_ecs/src/hierarchy.rs +++ b/crates/bevy_ecs/src/hierarchy.rs @@ -22,7 +22,9 @@ use core::slice; use disqualified::ShortName; use log::warn; -/// A [`Relationship`](crate::relationship::Relationship) component that creates the canonical +/// Stores the parent entity of the child entity with this component. +/// +/// This is a [`Relationship`](crate::relationship::Relationship) component, and creates the canonical /// "parent / child" hierarchy. This is the "source of truth" component, and it pairs with /// the [`Children`] [`RelationshipTarget`](crate::relationship::RelationshipTarget). /// @@ -31,7 +33,6 @@ use log::warn; /// 1. Organizing entities in a scene /// 2. Propagating configuration or data inherited from a parent, such as "visibility" or "world-space global transforms". /// 3. Ensuring a hierarchy is despawned when an entity is despawned. -/// 4. /// /// [`ChildOf`] contains a single "target" [`Entity`]. When [`ChildOf`] is inserted on a "source" entity, /// the "target" entity will automatically (and immediately, via a component hook) have a [`Children`] @@ -121,11 +122,18 @@ impl FromWorld for ChildOf { } } -/// A [`RelationshipTarget`](crate::relationship::RelationshipTarget) collection component that is populated +/// Tracks which entities are children of this parent entity. +/// +/// A [`RelationshipTarget`] collection component that is populated /// with entities that "target" this entity with the [`ChildOf`] [`Relationship`](crate::relationship::Relationship) component. /// -/// Together, these components form the "canonical parent-child hierarchy". See the [`ChildOf`] component for all full +/// Together, these components form the "canonical parent-child hierarchy". See the [`ChildOf`] component for the full /// description of this relationship and instructions on how to use it. +/// +/// Like all [`RelationshipTarget`] components, this data should not be directly manipulated to avoid desynchronization. +/// Instead, modify the [`ChildOf`] components on the "source" entities. +/// +/// [`RelationshipTarget`]: crate::relationship::RelationshipTarget #[derive(Component, Default, Debug, PartialEq, Eq)] #[relationship_target(relationship = ChildOf, linked_spawn)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] From a29a12a5b7730dc6ff5fb2c7135bf13af253f7f8 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 16 Feb 2025 14:09:45 -0800 Subject: [PATCH 2/4] Add doc aliases --- crates/bevy_ecs/src/hierarchy.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/bevy_ecs/src/hierarchy.rs b/crates/bevy_ecs/src/hierarchy.rs index f2ddfa3b6250e..a7638f8cf2843 100644 --- a/crates/bevy_ecs/src/hierarchy.rs +++ b/crates/bevy_ecs/src/hierarchy.rs @@ -93,6 +93,7 @@ use log::warn; reflect(Component, PartialEq, Debug, FromWorld) )] #[relationship(relationship_target = Children)] +#[doc(alias = "IsChild", alias = "Parent")] pub struct ChildOf(pub Entity); impl ChildOf { @@ -138,6 +139,7 @@ impl FromWorld for ChildOf { #[relationship_target(relationship = ChildOf, linked_spawn)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] #[cfg_attr(feature = "bevy_reflect", reflect(Component, FromWorld))] +#[doc(alias = "IsParent")] pub struct Children(Vec); impl<'a> IntoIterator for &'a Children { From 84ba0a409e578e7c67938b1ce7f418b2e5bef061 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 16 Feb 2025 14:12:55 -0800 Subject: [PATCH 3/4] Better usage notes --- crates/bevy_ecs/src/hierarchy.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/hierarchy.rs b/crates/bevy_ecs/src/hierarchy.rs index a7638f8cf2843..c92bb0984c93f 100644 --- a/crates/bevy_ecs/src/hierarchy.rs +++ b/crates/bevy_ecs/src/hierarchy.rs @@ -97,7 +97,7 @@ use log::warn; pub struct ChildOf(pub Entity); impl ChildOf { - /// Returns the "target" entity. + /// Returns the parent entity, which is the "target" of this relationship. pub fn get(&self) -> Entity { self.0 } @@ -131,9 +131,15 @@ impl FromWorld for ChildOf { /// Together, these components form the "canonical parent-child hierarchy". See the [`ChildOf`] component for the full /// description of this relationship and instructions on how to use it. /// +/// # Usage +/// /// Like all [`RelationshipTarget`] components, this data should not be directly manipulated to avoid desynchronization. /// Instead, modify the [`ChildOf`] components on the "source" entities. /// +/// To access the children of an entity, you can iterate over the [`Children`] component, +/// using the [`IntoIterator`] trait. +/// For more complex access patterns, see the [`RelationshipTarget`] trait. +/// /// [`RelationshipTarget`]: crate::relationship::RelationshipTarget #[derive(Component, Default, Debug, PartialEq, Eq)] #[relationship_target(relationship = ChildOf, linked_spawn)] From f3d967929a1b67e2e88c995ce6b288230e607294 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 16 Feb 2025 20:31:37 -0500 Subject: [PATCH 4/4] Clarify component ownership Co-authored-by: Eagster <79881080+ElliottjPierce@users.noreply.github.com> --- crates/bevy_ecs/src/hierarchy.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/hierarchy.rs b/crates/bevy_ecs/src/hierarchy.rs index c92bb0984c93f..2c4736d19b4a4 100644 --- a/crates/bevy_ecs/src/hierarchy.rs +++ b/crates/bevy_ecs/src/hierarchy.rs @@ -22,7 +22,7 @@ use core::slice; use disqualified::ShortName; use log::warn; -/// Stores the parent entity of the child entity with this component. +/// Stores the parent entity of this child entity with this component. /// /// This is a [`Relationship`](crate::relationship::Relationship) component, and creates the canonical /// "parent / child" hierarchy. This is the "source of truth" component, and it pairs with