Auto merge of #30061 - tshepang:doc-time, r=brson

src/libstd/time/mod.rs

@@ -22,22 +22,21 @@ pub use self::duration::Duration;
 
 mod duration;
 
-/// A measurement of a monotonically increasing clock which is suitable for
-/// measuring the amount of time that an operation takes.
+/// A measurement of a monotonically increasing clock.
 ///
-/// Instants are guaranteed always be greater than any previously measured
+/// Instants are always guaranteed to be greater 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.
+/// 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 but instead it only
-/// allow learning the duration between two instants (or comparing two
+/// 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).
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[unstable(feature = "time2", reason = "recently added", issue = "29866")]
@@ -60,7 +59,7 @@ pub struct Instant(time::Instant);
 /// Although a `SystemTime` cannot be directly inspected, the `UNIX_EPOCH`
 /// constant is provided in this module as an anchor in time to learn
 /// information about a `SystemTime`. By calculating the duration from this
-/// fixed point in time a `SystemTime` can be converted to a human-readable time
+/// fixed point in time, a `SystemTime` can be converted to a human-readable time,
 /// or perhaps some other string representation.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[unstable(feature = "time2", reason = "recently added", issue = "29866")]
@@ -95,8 +94,9 @@ impl Instant {
     ///
     /// # Panics
     ///
-    /// This function may panic if the current time is earlier than this instant
-    /// which can happen if an `Instant` is produced synthetically.
+    /// This function may panic if the current time is earlier than this
+    /// instant, which is something that can happen if an `Instant` is
+    /// produced synthetically.
     pub fn elapsed(&self) -> Duration {
         Instant::now().duration_from_earlier(*self)
     }
@@ -140,7 +140,7 @@ impl SystemTime {
     /// guaranteed to always be before later measurements (due to anomalies such
     /// as the system clock being adjusted either forwards or backwards).
     ///
-    /// If successful, `Ok(duration)` is returned where the duration represents
+    /// If successful, `Ok(Duration)` is returned where the duration represents
     /// the amount of time elapsed from the specified measurement to this one.
     ///
     /// Returns an `Err` if `earlier` is later than `self`, and the error
@@ -207,9 +207,8 @@ impl SystemTimeError {
     /// second system time was from the first.
     ///
     /// A `SystemTimeError` is returned from the `duration_from_earlier`
-    /// operation whenever the second duration, `earlier`, actually represents a
-    /// point later in time than the `self` of the method call. This function
-    /// will extract and return the amount of time later `earlier` actually is.
+    /// operation whenever the second system time represents a point later
+    /// in time than the `self` of the method call.
     pub fn duration(&self) -> Duration {
         self.0
     }