Improved the documentation of Duration constructors

  - Added Panics and Errors sections where appropriate, as these are
    generally-expected and help draw attention to the fact that the
    standard (i.e. non-try) constructors can panic. The Errors section
    for the try constructors is common practice when returning None for
    overflow situations as well as for functions actually returning a
    Result.

  - Added an further explanation of the behaviour of the seconds()
    constructor.

  - Minor additional readability edits.

src/duration.rs

@@ -76,86 +76,131 @@ pub(crate) const MAX: Duration = Duration {
 };
 
 impl Duration {
- /// Makes a new `Duration` with given number of weeks.
- /// Equivalent to `Duration::seconds(weeks * 7 * 24 * 60 * 60)` with overflow checks.
+ /// Makes a new `Duration` with the given number of weeks.
+ ///
+ /// Equivalent to `Duration::seconds(weeks * 7 * 24 * 60 * 60)` with
+ /// overflow checks.
+ ///
+ /// # Panics
+ ///
  /// Panics when the duration is out of bounds.
  #[inline]
  #[must_use]
  pub fn weeks(weeks: i64) -> Duration {
  Duration::try_weeks(weeks).expect("Duration::weeks out of bounds")
  }
 
- /// Makes a new `Duration` with given number of weeks.
- /// Equivalent to `Duration::seconds(weeks * 7 * 24 * 60 * 60)` with overflow checks.
+ /// Makes a new `Duration` with the given number of weeks.
+ ///
+ /// Equivalent to `Duration::seconds(weeks * 7 * 24 * 60 * 60)` with
+ /// overflow checks.
+ ///
+ /// # Errors
+ ///
  /// Returns `None` when the duration is out of bounds.
  #[inline]
  pub fn try_weeks(weeks: i64) -> Option<Duration> {
  weeks.checked_mul(SECS_PER_WEEK).and_then(Duration::try_seconds)
  }
 
- /// Makes a new `Duration` with given number of days.
- /// Equivalent to `Duration::seconds(days * 24 * 60 * 60)` with overflow checks.
+ /// Makes a new `Duration` with the given number of days.
+ ///
+ /// Equivalent to `Duration::seconds(days * 24 * 60 * 60)` with overflow
+ /// checks.
+ ///
+ /// # Panics
+ ///
  /// Panics when the duration is out of bounds.
  #[inline]
  #[must_use]
  pub fn days(days: i64) -> Duration {
  Duration::try_days(days).expect("Duration::days out of bounds")
  }
 
- /// Makes a new `Duration` with given number of days.
- /// Equivalent to `Duration::seconds(days * 24 * 60 * 60)` with overflow checks.
+ /// Makes a new `Duration` with the given number of days.
+ ///
+ /// Equivalent to `Duration::seconds(days * 24 * 60 * 60)` with overflow
+ /// checks.
+ ///
+ /// # Errors
+ ///
  /// Returns `None` when the duration is out of bounds.
  #[inline]
  pub fn try_days(days: i64) -> Option<Duration> {
  days.checked_mul(SECS_PER_DAY).and_then(Duration::try_seconds)
  }
 
- /// Makes a new `Duration` with given number of hours.
+ /// Makes a new `Duration` with the given number of hours.
+ ///
  /// Equivalent to `Duration::seconds(hours * 60 * 60)` with overflow checks.
+ ///
+ /// # Panics
+ ///
  /// Panics when the duration is out of bounds.
  #[inline]
  #[must_use]
  pub fn hours(hours: i64) -> Duration {
  Duration::try_hours(hours).expect("Duration::hours ouf of bounds")
  }
 
- /// Makes a new `Duration` with given number of hours.
+ /// Makes a new `Duration` with the given number of hours.
+ ///
  /// Equivalent to `Duration::seconds(hours * 60 * 60)` with overflow checks.
+ ///
+ /// # Errors
+ ///
  /// Returns `None` when the duration is out of bounds.
  #[inline]
  pub fn try_hours(hours: i64) -> Option<Duration> {
  hours.checked_mul(SECS_PER_HOUR).and_then(Duration::try_seconds)
  }
 
- /// Makes a new `Duration` with given number of minutes.
+ /// Makes a new `Duration` with the given number of minutes.
+ ///
  /// Equivalent to `Duration::seconds(minutes * 60)` with overflow checks.
+ ///
+ /// # Panics
+ ///
  /// Panics when the duration is out of bounds.
  #[inline]
  #[must_use]
  pub fn minutes(minutes: i64) -> Duration {
  Duration::try_minutes(minutes).expect("Duration::minutes out of bounds")
  }
 
- /// Makes a new `Duration` with given number of minutes.
+ /// Makes a new `Duration` with the given number of minutes.
+ ///
  /// Equivalent to `Duration::seconds(minutes * 60)` with overflow checks.
+ ///
+ /// # Errors
+ ///
  /// Returns `None` when the duration is out of bounds.
  #[inline]
  pub fn try_minutes(minutes: i64) -> Option<Duration> {
  minutes.checked_mul(SECS_PER_MINUTE).and_then(Duration::try_seconds)
  }
 
- /// Makes a new `Duration` with given number of seconds.
- /// Panics when the duration is more than `i64::MAX` milliseconds
- /// or less than `-i64::MAX` milliseconds.
+ /// Makes a new `Duration` with the given number of seconds.
+ ///
+ /// # Panics
+ ///
+ /// Panics when the duration is out of bounds, i.e. when the value is more
+ /// than `i64::MAX / 1_000` seconds or less than `-i64::MAX / 1_000` seconds
+ /// (in this context, this is the same as `i64::MIN / 1_000` due to
+ /// rounding).
  #[inline]
  #[must_use]
  pub fn seconds(seconds: i64) -> Duration {
  Duration::try_seconds(seconds).expect("Duration::seconds out of bounds")
  }
 
- /// Makes a new `Duration` with given number of seconds.
- /// Returns `None` when the duration is more than `i64::MAX` milliseconds
- /// or less than `-i64::MAX` milliseconds.
+ /// Makes a new `Duration` with the given number of seconds.
+ ///
+ /// # Errors
+ ///
+ /// Returns `None` when the duration is more than `i64::MAX / 1_000` seconds
+ /// or less than `-i64::MAX / 1_000` seconds (in this context, this is the
+ /// same as `i64::MIN / 1_000` due to rounding).
  #[inline]
  pub fn try_seconds(seconds: i64) -> Option<Duration> {
  let d = Duration { secs: seconds, nanos: 0 };
@@ -165,23 +210,23 @@ impl Duration {
  Some(d)
  }
 
- /// Makes a new `Duration` with given number of milliseconds.
+ /// Makes a new `Duration` with the given number of milliseconds.
  #[inline]
  pub const fn milliseconds(milliseconds: i64) -> Duration {
  let (secs, millis) = div_mod_floor_64(milliseconds, MILLIS_PER_SEC);
  let nanos = millis as i32 * NANOS_PER_MILLI;
  Duration { secs, nanos }
  }
 
- /// Makes a new `Duration` with given number of microseconds.
+ /// Makes a new `Duration` with the given number of microseconds.
  #[inline]
  pub const fn microseconds(microseconds: i64) -> Duration {
  let (secs, micros) = div_mod_floor_64(microseconds, MICROS_PER_SEC);
  let nanos = micros as i32 * NANOS_PER_MICRO;
  Duration { secs, nanos }
  }
 
- /// Makes a new `Duration` with given number of nanoseconds.
+ /// Makes a new `Duration` with the given number of nanoseconds.
  #[inline]
  pub const fn nanoseconds(nanos: i64) -> Duration {
  let (secs, nanos) = div_mod_floor_64(nanos, NANOS_PER_SEC as i64);