From faf59853f944f99c1871d54f2ebaf253ddaadaaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20M=2E=20Bezerra?= <marcospb19@hotmail.com>
Date: Sun, 29 Aug 2021 15:58:20 -0300
Subject: [PATCH] Adding examples to docs of std::time module

And adding missing link to Duration from Instant
---
 library/core/src/time.rs | 17 ++++++++++++-----
 library/std/src/time.rs  | 31 +++++++++++++++++++++++++------
 2 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/library/core/src/time.rs b/library/core/src/time.rs
index 2d8a1cb1ab0..35b740cd743 100644
--- a/library/core/src/time.rs
+++ b/library/core/src/time.rs
@@ -2,14 +2,21 @@
 
 //! Temporal quantification.
 //!
-//! Example:
+//! # Examples:
+//!
+//! There are multiple ways to create a new [`Duration`]:
 //!
 //! ```
-//! use std::time::Duration;
+//! # use std::time::Duration;
+//! let five_seconds = Duration::from_secs(5);
+//! assert_eq!(five_seconds, Duration::from_millis(5_000));
+//! assert_eq!(five_seconds, Duration::from_micros(5_000_000));
+//! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000));
 //!
-//! let five_seconds = Duration::new(5, 0);
-//! // both declarations are equivalent
-//! assert_eq!(Duration::new(5, 0), Duration::from_secs(5));
+//! let ten_seconds = Duration::from_secs(10);
+//! let seven_nanos = Duration::from_nanos(7);
+//! let total = ten_seconds + seven_nanos;
+//! assert_eq!(total, Duration::new(10, 7));
 //! ```
 
 use crate::fmt;
diff --git a/library/std/src/time.rs b/library/std/src/time.rs
index ec105f231e5..e9207ee3617 100644
--- a/library/std/src/time.rs
+++ b/library/std/src/time.rs
@@ -1,13 +1,32 @@
 //! Temporal quantification.
 //!
-//! Example:
+//! # Examples:
+//!
+//! There are multiple ways to create a new [`Duration`]:
 //!
 //! ```
-//! use std::time::Duration;
+//! # use std::time::Duration;
+//! let five_seconds = Duration::from_secs(5);
+//! assert_eq!(five_seconds, Duration::from_millis(5_000));
+//! assert_eq!(five_seconds, Duration::from_micros(5_000_000));
+//! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000));
 //!
-//! let five_seconds = Duration::new(5, 0);
-//! // both declarations are equivalent
-//! assert_eq!(Duration::new(5, 0), Duration::from_secs(5));
+//! let ten_seconds = Duration::from_secs(10);
+//! let seven_nanos = Duration::from_nanos(7);
+//! let total = ten_seconds + seven_nanos;
+//! assert_eq!(total, Duration::new(10, 7));
+//! ```
+//!
+//! Using [`Instant`] to calculate how long a function took to run:
+//!
+//! ```ignore (incomplete)
+//! let now = Instant::now();
+//!
+//! // Calling a slow function, it may take a while
+//! slow_function();
+//!
+//! let elapsed_time = now.elapsed();
+//! println!("Running slow_function() took {} seconds.", elapsed_time.as_secs());
 //! ```
 
 #![stable(feature = "time", since = "1.3.0")]
@@ -26,7 +45,7 @@ use crate::sys_common::FromInner;
 pub use core::time::Duration;
 
 /// A measurement of a monotonically nondecreasing clock.
-/// Opaque and useful only with `Duration`.
+/// 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