Small Commands error handling cleanup (#17904)

- Remove references to the short-lived `CommandError` type.
- Add a sentence to the explanation of error handlers.
- Clean up spacing/linebreaks.
- Use `where` notation for command-related trait `impl`s to make the big
ones easier to parse.

Author: JaySpruce

crates/bevy_ecs/src/system/commands/command.rs

@@ -79,7 +79,11 @@ pub trait HandleError<Out = ()> {
     }
 }
 
-impl<C: Command<Result<T, E>>, T, E: Into<Error>> HandleError<Result<T, E>> for C {
+impl<C, T, E> HandleError<Result<T, E>> for C
+where
+    C: Command<Result<T, E>>,
+    E: Into<Error>,
+{
     fn handle_error_with(self, error_handler: fn(&mut World, Error)) -> impl Command {
         move |world: &mut World| match self.apply(world) {
             Ok(_) => {}
@@ -88,7 +92,10 @@ impl<C: Command<Result<T, E>>, T, E: Into<Error>> HandleError<Result<T, E>> for
     }
 }
 
-impl<C: Command> HandleError for C {
+impl<C> HandleError for C
+where
+    C: Command,
+{
     #[inline]
     fn handle_error_with(self, _error_handler: fn(&mut World, Error)) -> impl Command {
         self

crates/bevy_ecs/src/system/commands/entity_command.rs

@@ -5,6 +5,7 @@
 //! [`EntityCommands`](crate::system::EntityCommands).
 
 use alloc::vec::Vec;
+use core::fmt;
 use log::info;
 
 use crate::{
@@ -79,8 +80,7 @@ use bevy_ptr::OwningPtr;
 /// }
 /// ```
 pub trait EntityCommand<Out = ()>: Send + 'static {
-    /// Executes this command for the given [`Entity`] and
-    /// returns a [`Result`] for error handling.
+    /// Executes this command for the given [`Entity`].
     fn apply(self, entity: EntityWorldMut) -> Out;
 }
 /// Passes in a specific entity to an [`EntityCommand`], resulting in a [`Command`] that
@@ -96,7 +96,10 @@ pub trait CommandWithEntity<Out> {
     fn with_entity(self, entity: Entity) -> impl Command<Out> + HandleError<Out>;
 }
 
-impl<C: EntityCommand> CommandWithEntity<Result<(), EntityMutableFetchError>> for C {
+impl<C> CommandWithEntity<Result<(), EntityMutableFetchError>> for C
+where
+    C: EntityCommand,
+{
     fn with_entity(
         self,
         entity: Entity,
@@ -110,11 +113,10 @@ impl<C: EntityCommand> CommandWithEntity<Result<(), EntityMutableFetchError>> fo
     }
 }
 
-impl<
-        C: EntityCommand<Result<T, Err>>,
-        T,
-        Err: core::fmt::Debug + core::fmt::Display + Send + Sync + 'static,
-    > CommandWithEntity<Result<T, EntityCommandError<Err>>> for C
+impl<C, T, Err> CommandWithEntity<Result<T, EntityCommandError<Err>>> for C
+where
+    C: EntityCommand<Result<T, Err>>,
+    Err: fmt::Debug + fmt::Display + Send + Sync + 'static,
 {
     fn with_entity(
         self,
@@ -245,8 +247,9 @@ pub fn retain<T: Bundle>() -> impl EntityCommand {
 ///
 /// # Note
 ///
-/// This will also despawn any [`Children`](crate::hierarchy::Children) entities, and any other [`RelationshipTarget`](crate::relationship::RelationshipTarget) that is configured
-/// to despawn descendants. This results in "recursive despawn" behavior.
+/// This will also despawn any [`Children`](crate::hierarchy::Children) entities,
+/// and any other [`RelationshipTarget`](crate::relationship::RelationshipTarget) that is configured to despawn descendants.
+/// This results in "recursive despawn" behavior.
 #[track_caller]
 pub fn despawn() -> impl EntityCommand {
     let caller = MaybeLocation::caller();

crates/bevy_ecs/src/system/commands/mod.rs

@@ -89,14 +89,19 @@ use crate::{
 ///
 /// # Error handling
 ///
-/// Commands can return a [`Result`](crate::result::Result), which can be passed to
-/// an error handler. Error handlers are functions/closures of the form
-/// `fn(&mut World, CommandError)`.
+/// A [`Command`] can return a [`Result`](crate::result::Result),
+/// which will be passed to an error handler if the `Result` is an error.
 ///
-/// The default error handler panics. It can be configured by enabling the `configurable_error_handler`
-/// cargo feature, then setting the `GLOBAL_ERROR_HANDLER`.
+/// Error handlers are functions/closures of the form `fn(&mut World, Error)`.
+/// They are granted exclusive access to the [`World`], which enables them to
+/// respond to the error in whatever way is necessary.
 ///
-/// Alternatively, you can customize the error handler for a specific command by calling [`Commands::queue_handled`].
+/// The [default error handler](error_handler::default) panics.
+/// It can be configured by enabling the `configurable_error_handler` cargo feature,
+/// then setting the `GLOBAL_ERROR_HANDLER`.
+///
+/// Alternatively, you can customize the error handler for a specific command
+/// by calling [`Commands::queue_handled`].
 ///
 /// The [`error_handler`] module provides some simple error handlers for convenience.
 ///
@@ -546,7 +551,8 @@ impl<'w, 's> Commands<'w, 's> {
 
     /// Pushes a generic [`Command`] to the command queue.
     ///
-    /// If the [`Command`] returns a [`Result`], it will be handled using the [default error handler](error_handler::default).
+    /// If the [`Command`] returns a [`Result`],
+    /// it will be handled using the [default error handler](error_handler::default).
     ///
     /// To use a custom error handler, see [`Commands::queue_handled`].
     ///
@@ -589,8 +595,11 @@ impl<'w, 's> Commands<'w, 's> {
     pub fn queue<C: Command<T> + HandleError<T>, T>(&mut self, command: C) {
         self.queue_internal(command.handle_error());
     }
-    /// Pushes a generic [`Command`] to the command queue. If the command returns a [`Result`] the given
-    /// `error_handler` will be used to handle error cases.
+
+    /// Pushes a generic [`Command`] to the command queue.
+    ///
+    /// If the [`Command`] returns a [`Result`],
+    /// the given `error_handler` will be used to handle error cases.
     ///
     /// To implicitly use the default error handler, see [`Commands::queue`].
     ///
@@ -1137,7 +1146,7 @@ impl<'w, 's> Commands<'w, 's> {
 /// Most [`Commands`] (and thereby [`EntityCommands`]) are deferred: when you call the command,
 /// if it requires mutable access to the [`World`] (that is, if it removes, adds, or changes something),
 /// it's not executed immediately. Instead, the command is added to a "command queue."
-/// The command queue is applied between [`Schedules`](bevy_ecs::schedule::Schedule), one by one,
+/// The command queue is applied between [`Schedules`](crate::schedule::Schedule), one by one,
 /// so that each command can have exclusive access to the World.
 ///
 /// # Fallible
@@ -1148,14 +1157,19 @@ impl<'w, 's> Commands<'w, 's> {
 ///
 /// # Error handling
 ///
-/// [`EntityCommands`] can return a [`Result`](crate::result::Result), which can be passed to
-/// an error handler. Error handlers are functions/closures of the form
-/// `fn(&mut World, CommandError)`.
+/// An [`EntityCommand`] can return a [`Result`](crate::result::Result),
+/// which will be passed to an error handler if the `Result` is an error.
+///
+/// Error handlers are functions/closures of the form `fn(&mut World, Error)`.
+/// They are granted exclusive access to the [`World`], which enables them to
+/// respond to the error in whatever way is necessary.
 ///
-/// The default error handler panics. It can be configured by enabling the `configurable_error_handler`
-/// cargo feature, then setting the `GLOBAL_ERROR_HANDLER`.
+/// The [default error handler](error_handler::default) panics.
+/// It can be configured by enabling the `configurable_error_handler` cargo feature,
+/// then setting the `GLOBAL_ERROR_HANDLER`.
 ///
-/// Alternatively, you can customize the error handler for a specific command by calling [`EntityCommands::queue_handled`].
+/// Alternatively, you can customize the error handler for a specific command
+/// by calling [`EntityCommands::queue_handled`].
 ///
 /// The [`error_handler`] module provides some simple error handlers for convenience.
 pub struct EntityCommands<'a> {
@@ -1754,7 +1768,8 @@ impl<'a> EntityCommands<'a> {
 
     /// Pushes an [`EntityCommand`] to the queue, which will get executed for the current [`Entity`].
     ///
-    /// If the [`EntityCommand`] returns a [`Result`], it will be handled using the [default error handler](error_handler::default).
+    /// If the [`EntityCommand`] returns a [`Result`],
+    /// it will be handled using the [default error handler](error_handler::default).
     ///
     /// To use a custom error handler, see [`EntityCommands::queue_handled`].
     ///
@@ -1788,7 +1803,9 @@ impl<'a> EntityCommands<'a> {
     }
 
     /// Pushes an [`EntityCommand`] to the queue, which will get executed for the current [`Entity`].
-    /// If the command returns a [`Result`] the given `error_handler` will be used to handle error cases.
+    ///
+    /// If the [`EntityCommand`] returns a [`Result`],
+    /// the given `error_handler` will be used to handle error cases.
     ///
     /// To implicitly use the default error handler, see [`EntityCommands::queue`].
     ///