Added docs on how Parent component is affected by BuildChildren m…

…ethods. (#17205)

`BuildChildren` docs didn't specify how the children's `Parent`
components are changed, which is now fixed.
Fixes #16526.

crates/bevy_hierarchy/src/child_builder.rs

@@ -248,6 +248,8 @@ pub trait BuildChildren {
 
     /// Spawns the passed bundle and adds it to this entity as a child.
     ///
+    /// The bundle's [`Parent`] component will be updated to the new parent.
+    ///
     /// For efficient spawning of multiple children, use [`with_children`].
     ///
     /// [`with_children`]: BuildChildren::with_children
@@ -256,6 +258,8 @@ pub trait BuildChildren {
     /// Pushes children to the back of the builder's children. For any entities that are
     /// already a child of this one, this method does nothing.
     ///
+    /// The children's [`Parent`] component will be updated to the new parent.
+    ///
     /// If the children were previously children of another parent, that parent's [`Children`] component
     /// will have those children removed from its list. Removing all children from a parent causes its
     /// [`Children`] component to be removed from the entity.
@@ -267,6 +271,8 @@ pub trait BuildChildren {
 
     /// Inserts children at the given index.
     ///
+    /// The children's [`Parent`] component will be updated to the new parent.
+    ///
     /// If the children were previously children of another parent, that parent's [`Children`] component
     /// will have those children removed from its list. Removing all children from a parent causes its
     /// [`Children`] component to be removed from the entity.
@@ -276,13 +282,17 @@ pub trait BuildChildren {
     /// Panics if any of the children are the same as the parent.
     fn insert_children(&mut self, index: usize, children: &[Entity]) -> &mut Self;
 
-    /// Removes the given children
+    /// Removes the given children.
+    ///
+    /// The removed children will have their [`Parent`] component removed.
     ///
     /// Removing all children from a parent causes its [`Children`] component to be removed from the entity.
     fn remove_children(&mut self, children: &[Entity]) -> &mut Self;
 
     /// Adds a single child.
     ///
+    /// The child's [`Parent`] component will be updated to the new parent.
+    ///
     /// If the child was previously the child of another parent, that parent's [`Children`] component
     /// will have the child removed from its list. Removing all children from a parent causes its
     /// [`Children`] component to be removed from the entity.
@@ -292,11 +302,13 @@ pub trait BuildChildren {
     /// Panics if the child is the same as the parent.
     fn add_child(&mut self, child: Entity) -> &mut Self;
 
-    /// Removes all children from this entity. The [`Children`] component will be removed if it exists, otherwise this does nothing.
+    /// Removes all children from this entity. The [`Children`] component and the children's [`Parent`] component will be removed.
+    /// If the [`Children`] component is not present, this has no effect.
     fn clear_children(&mut self) -> &mut Self;
 
     /// Removes all current children from this entity, replacing them with the specified list of entities.
     ///
+    /// The added children's [`Parent`] component will be updated to the new parent.
     /// The removed children will have their [`Parent`] component removed.
     ///
     /// # Panics