fix: Update the docs of "pause" to state that time will still advance (#2647)

* doc: Update the docs of "pause" to state that time will still advance

This was changed in #2059. This had me extremely confused for some time
as my timeouts fired immediately, without the wrapped future that were
waiting on IO to actually run long enough.

I am not sure about the exact wording here but this had me very confused
for some time. Deprecating "pause" and giving it a more accurate name
may be a good idea as well.

```rust
async fn timeout_advances() {
    time::pause();

    timeout(ms(1), async {
        // Change to 1 and the this future resolve, 2 or
        // more and the timeout resolves
        for _ in 0..2 {
            tokio::task::yield_now().await
        }
    })
    .await
    .unwrap();
}

```

* Update tokio/src/time/clock.rs

Co-authored-by: Alice Ryhl <alice@ryhl.io>

Co-authored-by: Alice Ryhl <alice@ryhl.io>

1 files changed, 3 insertions, 2 deletions

diff --git a/tokio/src/time/clock.rs b/tokio/src/time/clock.rs
index 4ac24af3..bd67d7a3 100644
--- a/tokio/src/time/clock.rs
+++ b/tokio/src/time/clock.rs
@@ -56,8 +56,9 @@ cfg_test_util! {
     /// Pause time
     ///
     /// The current value of `Instant::now()` is saved and all subsequent calls
-    /// to `Instant::now()` will return the saved value. This is useful for
-    /// running tests that are dependent on time.
+    /// to `Instant::now()` until the timer wheel is checked again will return the saved value.
+    /// Once the timer wheel is checked, time will immediately advance to the next registered
+    /// `Delay`. This is useful for running tests that depend on time.
     ///
     /// # Panics
     ///