task: explain why yield_now defers its waker (#8254)

Since #5223, `yield_now` does not wake the task immediately. Instead,
the waker is handed to the scheduler via `context::defer`, which wakes
it only after running out of ready tasks and polling the IO/timer
driver. Add a comment explaining this, as the reasoning is not obvious
from the bare `context::defer` call.

tokio/src/task/yield_now.rs

@@ -46,6 +46,12 @@ pub async fn yield_now() {
 
         yielded = true;
 
+        // Don't wake the task immediately, as that would push it right back
+        // onto the run queue and it could be polled again before other tasks
+        // or the IO/timer driver get a chance to run. Instead, hand the waker
+        // to the scheduler, which wakes deferred tasks only after it has run
+        // out of ready tasks and polled the driver. When polled from outside
+        // a Tokio runtime, the waker is woken immediately.
         context::defer(cx.waker());
 
         Poll::Pending