time: Clean up `Instant` docs to align with `std` (#2946)

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

1 files changed, 26 insertions, 2 deletions

diff --git a/tokio/src/time/instant.rs b/tokio/src/time/instant.rs
index e14a3004..f4d6eacb 100644
--- a/tokio/src/time/instant.rs
+++ b/tokio/src/time/instant.rs
@@ -4,8 +4,32 @@ use std::fmt;
 use std::ops;
 use std::time::Duration;
 
-/// A measurement of the system clock, useful for talking to
-/// external entities like the file system or other processes.
+/// A measurement of a monotonically nondecreasing clock.
+/// Opaque and useful only with `Duration`.
+///
+/// Instants are always guaranteed to be no less than any previously measured
+/// instant when created, and are often useful for tasks such as measuring
+/// benchmarks or timing how long an operation takes.
+///
+/// Note, however, that instants are not guaranteed to be **steady**. In other
+/// words, each tick of the underlying clock may not be the same length (e.g.
+/// some seconds may be longer than others). An instant may jump forwards or
+/// experience time dilation (slow down or speed up), but it will never go
+/// backwards.
+///
+/// Instants are opaque types that can only be compared to one another. There is
+/// no method to get "the number of seconds" from an instant. Instead, it only
+/// allows measuring the duration between two instants (or comparing two
+/// instants).
+///
+/// The size of an `Instant` struct may vary depending on the target operating
+/// system.
+///
+/// # Note
+///
+/// This type wraps the inner `std` variant and is used to align the Tokio
+/// clock for uses of `now()`. This can be useful for testing where you can
+/// take advantage of `time::pause()` and `time::advance()`.
 #[derive(Clone, Copy, Eq, PartialEq, PartialOrd, Ord, Hash)]
 pub struct Instant {
     std: std::time::Instant,