docs: more doc fixes (#2831)

Previous docs look like they were based on the docs for
`insert_at`. Changed names of variables referred to and the
explanation of when the value will be returned and under what
condition it will be immediately available to make sense for a
Duration argument instead of an Instant.

1 files changed, 14 insertions, 12 deletions

diff --git a/tokio/src/time/delay_queue.rs b/tokio/src/time/delay_queue.rs
index b02153b9..6f755eba 100644
--- a/tokio/src/time/delay_queue.rs
+++ b/tokio/src/time/delay_queue.rs
@@ -366,23 +366,25 @@ impl<T> DelayQueue<T> {
     /// This function is identical to `insert_at`, but takes a `Duration`
     /// instead of an `Instant`.
     ///
-    /// `value` is stored in the queue until `when` is reached. At which point,
-    /// `value` will be returned from [`poll_expired`]. If `when` has already been
-    /// reached, then `value` is immediately made available to poll.
-    ///
-    /// The return value represents the insertion and is used at an argument to
-    /// [`remove`] and [`reset`]. Note that [`Key`] is token and is reused once
-    /// `value` is removed from the queue either by calling [`poll_expired`] after
-    /// `when` is reached or by calling [`remove`]. At this point, the caller
-    /// must take care to not use the returned [`Key`] again as it may reference
-    /// a different item in the queue.
+    /// `value` is stored in the queue until `timeout` duration has
+    /// elapsed after `insert` was called. At that point, `value` will
+    /// be returned from [`poll_expired`]. If `timeout` a Duration of
+    /// zero, then `value` is immediately made available to poll.
+    ///
+    /// The return value represents the insertion and is used as an
+    /// argument to [`remove`] and [`reset`]. Note that [`Key`] is a
+    /// token and is reused once `value` is removed from the queue
+    /// either by calling [`poll_expired`] after `timeout` has elapsed
+    /// or by calling [`remove`]. At this point, the caller must not
+    /// use the returned [`Key`] again as it may reference a different
+    /// item in the queue.
     ///
     /// See [type] level documentation for more details.
     ///
     /// # Panics
     ///
-    /// This function panics if `timeout` is greater than the maximum supported
-    /// duration.
+    /// This function panics if `timeout` is greater than the maximum
+    /// duration supported by the timer in the current `Runtime`.
     ///
     /// # Examples
     ///