add some docs on scheduling

src/task.rs

@@ -19,7 +19,9 @@ use crate::work_stealing::WorkStealingExecutor;
 /// 1. an `async_task::Task<()>`, which we refer to as a `Runnable`
 /// 2. an `async_task::JoinHandle<T, ()>`, which is wrapped inside a `Task<T>`
 ///
-/// Once a `Runnable` is run, it "vanishes" and only reappears when its future is woken.
+/// Once a `Runnable` is run, it "vanishes" and only reappears when its future is woken. When it's
+/// woken up, its schedule function is called; in smol, that means that `Runnable` will be pushed
+/// onto a queue in an executor.
 pub(crate) type Runnable = async_task::Task<()>;
 
 /// A spawned future.

src/thread_local.rs

@@ -77,7 +77,7 @@ impl ThreadLocalExecutor {
             let event = ex.event.clone();
             let id = thread_id();
 
-            // The function that schedules a runnable task.
+            // The function that schedules a runnable task when it gets woken up.
             let schedule = move |runnable| {
                 if thread_id() == id {
                     // If scheduling from the original thread, push into the main queue.
@@ -93,7 +93,7 @@ impl ThreadLocalExecutor {
                 event.notify();
             };
 
-            // Create a task, schedule it, and return its `Task` handle.
+            // Create a task, push it into the queue by scheduling it, and return its `Task` handle.
             let (runnable, handle) = async_task::spawn_local(future, schedule, ());
             runnable.schedule();
             Task(Some(handle))

src/work_stealing.rs

@@ -79,7 +79,7 @@ impl WorkStealingExecutor {
         &'static self,
         future: impl Future<Output = T> + Send + 'static,
     ) -> Task<T> {
-        // The function that schedules a runnable task.
+        // The function that schedules a runnable task when it gets woken up.
         let schedule = move |runnable| {
             if WORKER.is_set() {
                 // If scheduling from a worker thread, push into the worker's queue.
@@ -93,7 +93,7 @@ impl WorkStealingExecutor {
             }
         };
 
-        // Create a task, schedule it, and return its `Task` handle.
+        // Create a task, push it into the queue by scheduling it, and return its `Task` handle.
         let (runnable, handle) = async_task::spawn(future, schedule, ());
         runnable.schedule();
         Task(Some(handle))