Document part of bevy_ecs::Commands

crates/bevy_ecs/src/core/world.rs

@@ -76,16 +76,16 @@ impl World {
     /// let a = world.spawn((123, "abc"));
     /// let b = world.spawn((456, true));
     /// ```
-    pub fn spawn(&mut self, components: impl DynamicBundle) -> Entity {
+    pub fn spawn(&mut self, bundle: impl DynamicBundle) -> Entity {
         // Ensure all entity allocations are accounted for so `self.entities` can realloc if
         // necessary
         self.flush();
 
         let entity = self.entities.alloc();
-        let archetype_id = components.with_ids(|ids| {
+        let archetype_id = bundle.with_ids(|ids| {
             self.index.get(ids).copied().unwrap_or_else(|| {
                 let x = self.archetypes.len() as u32;
-                self.archetypes.push(Archetype::new(components.type_info()));
+                self.archetypes.push(Archetype::new(bundle.type_info()));
                 self.index.insert(ids.to_vec(), x);
                 self.archetype_generation += 1;
                 x
@@ -95,7 +95,7 @@ impl World {
         let archetype = &mut self.archetypes[archetype_id as usize];
         unsafe {
             let index = archetype.allocate(entity);
-            components.put(|ptr, ty, size| {
+            bundle.put(|ptr, ty, size| {
                 archetype.put_dynamic(ptr, ty, size, index, ComponentFlags::ADDED);
                 true
             });
@@ -566,7 +566,7 @@ impl World {
     pub fn insert(
         &mut self,
         entity: Entity,
-        components: impl DynamicBundle,
+        bundle: impl DynamicBundle,
     ) -> Result<(), NoSuchEntity> {
         use std::collections::hash_map::Entry;
 
@@ -576,7 +576,7 @@ impl World {
             // Assemble Vec<TypeInfo> for the final entity
             let arch = &mut self.archetypes[loc.archetype as usize];
             let mut info = arch.types().to_vec();
-            for ty in components.type_info() {
+            for ty in bundle.type_info() {
                 if let Some(ptr) = arch.get_dynamic(ty.id(), ty.layout().size(), loc.index) {
                     ty.drop(ptr.as_ptr());
                 } else {
@@ -601,7 +601,7 @@ impl World {
             if target == loc.archetype {
                 // Update components in the current archetype
                 let arch = &mut self.archetypes[loc.archetype as usize];
-                components.put(|ptr, ty, size| {
+                bundle.put(|ptr, ty, size| {
                     arch.put_dynamic(ptr, ty, size, loc.index, ComponentFlags::MUTATED);
                     true
                 });
@@ -625,7 +625,7 @@ impl World {
                 self.entities.get_mut(moved).unwrap().index = old_index;
             }
 
-            components.put(|ptr, ty, size| {
+            bundle.put(|ptr, ty, size| {
                 let had_component = source_arch.has_dynamic(ty);
                 let flags = if had_component {
                     ComponentFlags::MUTATED

crates/bevy_ecs/src/system/commands.rs

@@ -16,15 +16,15 @@ pub(crate) struct Spawn<T>
 where
     T: DynamicBundle + Send + Sync + 'static,
 {
-    components: T,
+    bundle: T,
 }
 
 impl<T> Command for Spawn<T>
 where
     T: DynamicBundle + Send + Sync + 'static,
 {
     fn write(self: Box<Self>, world: &mut World, _resources: &mut Resources) {
-        world.spawn(self.components);
+        world.spawn(self.bundle);
     }
 }
 
@@ -33,7 +33,7 @@ where
     I: IntoIterator,
     I::Item: Bundle,
 {
-    components_iter: I,
+    bundles_iter: I,
 }
 
 impl<I> Command for SpawnBatch<I>
@@ -42,7 +42,7 @@ where
     I::Item: Bundle,
 {
     fn write(self: Box<Self>, world: &mut World, _resources: &mut Resources) {
-        world.spawn_batch(self.components_iter);
+        world.spawn_batch(self.bundles_iter);
     }
 }
 
@@ -64,15 +64,15 @@ where
     T: DynamicBundle + Send + Sync + 'static,
 {
     entity: Entity,
-    components: T,
+    bundle: T,
 }
 
 impl<T> Command for Insert<T>
 where
     T: DynamicBundle + Send + Sync + 'static,
 {
     fn write(self: Box<Self>, world: &mut World, _resources: &mut Resources) {
-        world.insert(self.entity, self.components).unwrap();
+        world.insert(self.entity, self.bundle).unwrap();
     }
 }
 
@@ -190,11 +190,11 @@ pub struct Commands {
 }
 
 impl Commands {
-    /// Creates a new entity and calls `insert` with the it and `components`.
+    /// Creates a new entity and calls `insert` with the it and `bundle`.
     ///
-    /// Note that `components` is a bundle. If you would like to spawn an entity with a single component, consider wrapping the component in a tuple (which `DynamicBundle` is implemented for).
+    /// Note that `bundle` is a bundle. If you would like to spawn an entity with a single component, consider wrapping the component in a tuple (which `Bundle` is implemented for).
     ///
-    /// See `set_current_entity`, `insert`.
+    /// See [`Commands::set_current_entity`], [`Commands::insert`].
     ///
     /// # Example
     ///
@@ -222,45 +222,47 @@ impl Commands {
     ///     commands.spawn((Component2,));
     /// }
     /// ```
-    pub fn spawn(&mut self, components: impl DynamicBundle + Send + Sync + 'static) -> &mut Self {
+    pub fn spawn(&mut self, bundle: impl DynamicBundle + Send + Sync + 'static) -> &mut Self {
         let entity = self
             .entity_reserver
             .as_ref()
             .expect("entity reserver has not been set")
             .reserve_entity();
         self.set_current_entity(entity);
-        self.insert(entity, components);
+        self.insert(entity, bundle);
         self
     }
 
-    /// Equivalent to iterating of `components_iter` and calling `spawn` on each bundle, but slightly more performant.
-    pub fn spawn_batch<I>(&mut self, components_iter: I) -> &mut Self
+    /// Equivalent to iterating of `bundles_iter` and calling `spawn` on each bundle, but slightly more performant.
+    pub fn spawn_batch<I>(&mut self, bundles_iter: I) -> &mut Self
     where
         I: IntoIterator + Send + Sync + 'static,
         I::Item: Bundle,
     {
-        self.add_command(SpawnBatch { components_iter })
+        self.add_command(SpawnBatch { bundles_iter })
     }
 
     /// Despawns only the specified entity, ignoring any other consideration.
+    ///
+    /// Note that this does not recursively despawn and entity's children.
     pub fn despawn(&mut self, entity: Entity) -> &mut Self {
         self.add_command(Despawn { entity })
     }
 
     /// Inserts a bundle of components into `entity`.
     ///
-    /// See `World::insert`.
+    /// See [`World::insert`].
     pub fn insert(
         &mut self,
         entity: Entity,
-        components: impl DynamicBundle + Send + Sync + 'static,
+        bundle: impl DynamicBundle + Send + Sync + 'static,
     ) -> &mut Self {
-        self.add_command(Insert { entity, components })
+        self.add_command(Insert { entity, bundle })
     }
 
     /// Inserts a single component into `entity`.
     ///
-    /// See `World::insert_one`.
+    /// See [`World::insert_one`].
     pub fn insert_one(&mut self, entity: Entity, component: impl Component) -> &mut Self {
         self.add_command(InsertOne { entity, component })
     }
@@ -280,7 +282,7 @@ impl Commands {
         })
     }
 
-    /// See `World::remove_one`.
+    /// See [`World::remove_one`].
     pub fn remove_one<T>(&mut self, entity: Entity) -> &mut Self
     where
         T: Component,
@@ -291,7 +293,7 @@ impl Commands {
         })
     }
 
-    /// See `World::remove`.
+    /// See [`World::remove`].
     pub fn remove<T>(&mut self, entity: Entity) -> &mut Self
     where
         T: Bundle + Send + Sync + 'static,
@@ -304,22 +306,19 @@ impl Commands {
 
     /// Adds a bundle of components to the current entity.
     ///
-    /// See `with`, `current_entity`.
-    pub fn with_bundle(
-        &mut self,
-        components: impl DynamicBundle + Send + Sync + 'static,
-    ) -> &mut Self {
-        let current_entity =  self.current_entity.expect("Cannot add components because the 'current entity' is not set. You should spawn an entity first.");
+    /// See [`Commands::with`], [`Commands::current_entity`].
+    pub fn with_bundle(&mut self, bundle: impl DynamicBundle + Send + Sync + 'static) -> &mut Self {
+        let current_entity =  self.current_entity.expect("Cannot add bundle because the 'current entity' is not set. You should spawn an entity first.");
         self.commands.push(Box::new(Insert {
             entity: current_entity,
-            components,
+            bundle,
         }));
         self
     }
 
     /// Adds a single component to the current entity.
     ///
-    /// See `with_bundle`, `current_entity`.
+    /// See [`Commands::with_bundle`], [`Commands::current_entity`].
     ///
     /// # Warning
     ///
@@ -362,13 +361,13 @@ impl Commands {
         self
     }
 
-    /// Adds a command directly to the command list. If `command` is boxed, call `add_command_boxed`.
+    /// Adds a command directly to the command list. Prefer this to `add_command_boxed` if the type of |command| is statically known.
     pub fn add_command<C: Command + 'static>(&mut self, command: C) -> &mut Self {
         self.commands.push(Box::new(command));
         self
     }
 
-    /// See `add_command`.
+    /// See [`Commands::add_command`].
     pub fn add_command_boxed(&mut self, command: Box<dyn Command>) -> &mut Self {
         self.commands.push(command);
         self