Rollup merge of #136301 - hkBst:patch-33, r=thomcc

Improve instant docs

This should be enough to close #79881.

1 files changed, 8 insertions, 2 deletions

diff --git a/library/std/src/time.rs b/library/std/src/time.rs
index 88b3e9e0ceb..5ab71413586 100644
--- a/library/std/src/time.rs
+++ b/library/std/src/time.rs
@@ -93,11 +93,17 @@ use crate::sys_common::{FromInner, IntoInner};
 /// use std::time::{Instant, Duration};
 ///
 /// let now = Instant::now();
-/// let max_seconds = u64::MAX / 1_000_000_000;
-/// let duration = Duration::new(max_seconds, 0);
+/// let days_per_10_millennia = 365_2425;
+/// let solar_seconds_per_day = 60 * 60 * 24;
+/// let millenium_in_solar_seconds = 31_556_952_000;
+/// assert_eq!(millenium_in_solar_seconds, days_per_10_millennia * solar_seconds_per_day / 10);
+///
+/// let duration = Duration::new(millenium_in_solar_seconds, 0);
 /// println!("{:?}", now + duration);
 /// ```
 ///
+/// For cross-platform code, you can comfortably use durations of up to around one hundred years.
+///
 /// # Underlying System calls
 ///
 /// The following system calls are [currently] being used by `now()` to find out