elaborate on TaskPool and bevy tasks

crates/bevy_tasks/src/task_pool.rs

@@ -93,8 +93,13 @@ impl TaskPoolBuilder {
     }
 }
 
-/// A thread pool for executing tasks. Tasks are futures that are being automatically driven by
-/// the pool on threads owned by the pool.
+/// A thread pool for executing tasks. While futures usually need to be polled
+/// to be executed, Bevy tasks are being automatically driven by the pool on
+/// threads owned by the pool. The [`Task`] future only needs to be polled in
+/// order to receive the result. (For that purpose, it is often stored in a
+/// component or resource, see the `async_compute` example.) If the result is
+/// not required, one may also use [`Task.detach`] and the pool will still
+/// execute a task, even if it is dropped.
 #[derive(Debug)]
 pub struct TaskPool {
     /// The executor for the pool

crates/bevy_tasks/src/usages.rs

@@ -17,8 +17,10 @@ static COMPUTE_TASK_POOL: OnceLock<ComputeTaskPool> = OnceLock::new();
 static ASYNC_COMPUTE_TASK_POOL: OnceLock<AsyncComputeTaskPool> = OnceLock::new();
 static IO_TASK_POOL: OnceLock<IoTaskPool> = OnceLock::new();
 
-/// A newtype for a task pool for CPU-intensive work that must be completed to deliver the next
-/// frame
+/// A newtype for a task pool for CPU-intensive work that must be completed to
+/// deliver the next frame. See [`TaskPool`] documentation for details on Bevy
+/// tasks. ['AsyncComputeTaskPool'] should be preferred if the work does not
+/// have to be completed before the next frame.
 #[derive(Debug)]
 pub struct ComputeTaskPool(TaskPool);
 
@@ -48,7 +50,8 @@ impl Deref for ComputeTaskPool {
     }
 }
 
-/// A newtype for a task pool for CPU-intensive work that may span across multiple frames
+/// A newtype for a task pool for CPU-intensive work that may span across multiple frames.
+/// See [`TaskPool`] documentation for details on Bevy tasks. Use [`ComputeTaskPool`] if 
 #[derive(Debug)]
 pub struct AsyncComputeTaskPool(TaskPool);
 

examples/async_tasks/async_compute.rs

@@ -54,7 +54,9 @@ fn spawn_tasks(mut commands: Commands) {
     for x in 0..NUM_CUBES {
         for y in 0..NUM_CUBES {
             for z in 0..NUM_CUBES {
-                // Spawn new task on the AsyncComputeTaskPool
+                // Spawn new task on the AsyncComputeTaskPool; the task will be
+                // executed in th background, and the Task future returned by
+                // spawn() can be used to poll for the result
                 let task = thread_pool.spawn(async move {
                     let mut rng = rand::thread_rng();
                     let start_time = Instant::now();