Document the return value of run()

1 files changed, 4 insertions, 3 deletions

diff --git a/src/runnable.rs b/src/runnable.rs
index be3e25f..adecbcb 100644
--- a/src/runnable.rs
+++ b/src/runnable.rs
@@ -276,9 +276,10 @@ impl Runnable {
     /// Runs the task by polling its future.
     ///
     /// Returns `true` if the task was woken while running, in which case the [`Runnable`] gets
-    /// rescheduled at the end of this method invocation.
-    ///
-    /// Otherwise, returns `true` and the [`Runnable`] vanishes until the task is woken.
+    /// rescheduled at the end of this method invocation. Otherwise, returns `false` and the
+    /// [`Runnable`] vanishes until the task is woken.
+    /// The return value is just a hint: `true` usually indicates that the task has yielded, i.e.
+    /// it woke itself and then gave the control back to the executor.
     ///
     /// If the [`Task`] handle was dropped or if [`cancel()`][`Task::cancel()`] was called, then
     /// this method simply destroys the task.