bevy_hierarchy: add some docs (#10598)

Just adding comments to code I did not understand before and I hope
understand now.

---------

Co-authored-by: Kristoffer Søholm <k.soeholm@gmail.com>

crates/bevy_hierarchy/src/child_builder.rs

@@ -253,6 +253,27 @@ impl Command for RemoveParent {
 }
 
 /// Struct for building children entities and adding them to a parent entity.
+///
+/// # Example
+///
+/// This example creates three entities, a parent and two children.
+///
+/// ```
+/// # use bevy_ecs::bundle::Bundle;
+/// # use bevy_ecs::system::Commands;
+/// # use bevy_hierarchy::BuildChildren;
+/// # #[derive(Bundle)]
+/// # struct MyBundle {}
+/// # #[derive(Bundle)]
+/// # struct MyChildBundle {}
+/// #
+/// # fn test(mut commands: Commands) {
+/// commands.spawn(MyBundle {}).with_children(|child_builder| {
+///     child_builder.spawn(MyChildBundle {});
+///     child_builder.spawn(MyChildBundle {});
+/// });
+/// # }
+/// ```
 pub struct ChildBuilder<'w, 's, 'a> {
     commands: &'a mut Commands<'w, 's>,
     push_children: PushChildren,

crates/bevy_hierarchy/src/components/children.rs

@@ -12,10 +12,17 @@ use std::ops::Deref;
 
 /// Contains references to the child entities of this entity.
 ///
+/// Each child must contain a [`Parent`] component that points back to this entity.
+/// This component rarely needs to be created manually,
+/// consider using higher level utilities like [`BuildChildren::with_children`]
+/// which are safer and easier to use.
+///
 /// See [`HierarchyQueryExt`] for hierarchy related methods on [`Query`].
 ///
 /// [`HierarchyQueryExt`]: crate::query_extension::HierarchyQueryExt
 /// [`Query`]: bevy_ecs::system::Query
+/// [`Parent`]: crate::components::parent::Parent
+/// [`BuildChildren::with_children`]: crate::child_builder::BuildChildren::with_children
 #[derive(Component, Debug, Reflect)]
 #[reflect(Component, MapEntities)]
 pub struct Children(pub(crate) SmallVec<[Entity; 8]>);

crates/bevy_hierarchy/src/components/parent.rs

@@ -10,10 +10,16 @@ use std::ops::Deref;
 /// Holds a reference to the parent entity of this entity.
 /// This component should only be present on entities that actually have a parent entity.
 ///
+/// Parent entity must have this entity stored in its [`Children`] component.
+/// It is hard to set up parent/child relationships manually,
+/// consider using higher level utilities like [`BuildChildren::with_children`].
+///
 /// See [`HierarchyQueryExt`] for hierarchy related methods on [`Query`].
 ///
 /// [`HierarchyQueryExt`]: crate::query_extension::HierarchyQueryExt
 /// [`Query`]: bevy_ecs::system::Query
+/// [`Children`]: super::children::Children
+/// [`BuildChildren::with_children`]: crate::child_builder::BuildChildren::with_children
 #[derive(Component, Debug, Eq, PartialEq, Reflect)]
 #[reflect(Component, MapEntities, PartialEq)]
 pub struct Parent(pub(crate) Entity);