Panic Documentation (#638)

time-rs · Dec 1, 2023 · 6d5fa1e · 6d5fa1e
1 parent bd92ba9
commit 6d5fa1e
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 0 deletions.
diff --git a/time/src/date.rs b/time/src/date.rs
@@ -1403,6 +1403,9 @@ impl fmt::Debug for Date {
 impl Add<Duration> for Date {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, duration: Duration) -> Self::Output {
         self.checked_add(duration)
             .expect("overflow adding duration to date")
@@ -1412,6 +1415,9 @@ impl Add<Duration> for Date {
 impl Add<StdDuration> for Date {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, duration: StdDuration) -> Self::Output {
         self.checked_add_std(duration)
             .expect("overflow adding duration to date")
@@ -1423,6 +1429,9 @@ impl_add_assign!(Date: Duration, StdDuration);
 impl Sub<Duration> for Date {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, duration: Duration) -> Self::Output {
         self.checked_sub(duration)
             .expect("overflow subtracting duration from date")
@@ -1432,6 +1441,9 @@ impl Sub<Duration> for Date {
 impl Sub<StdDuration> for Date {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, duration: StdDuration) -> Self::Output {
         self.checked_sub_std(duration)
             .expect("overflow subtracting duration from date")

diff --git a/time/src/date_time.rs b/time/src/date_time.rs
@@ -1009,6 +1009,9 @@ impl<O: MaybeOffset> Hash for DateTime<O> {
 impl<O: MaybeOffset> Add<Duration> for DateTime<O> {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, duration: Duration) -> Self {
         self.checked_add(duration)
             .expect("resulting value is out of range")
@@ -1018,6 +1021,9 @@ impl<O: MaybeOffset> Add<Duration> for DateTime<O> {
 impl<O: MaybeOffset> Add<StdDuration> for DateTime<O> {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, duration: StdDuration) -> Self::Output {
         let (is_next_day, time) = self.time.adjusting_add_std(duration);
 
@@ -1050,6 +1056,9 @@ impl<O: MaybeOffset> AddAssign<StdDuration> for DateTime<O> {
 impl<O: MaybeOffset> Sub<Duration> for DateTime<O> {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, duration: Duration) -> Self {
         self.checked_sub(duration)
             .expect("resulting value is out of range")
@@ -1059,6 +1068,9 @@ impl<O: MaybeOffset> Sub<Duration> for DateTime<O> {
 impl<O: MaybeOffset> Sub<StdDuration> for DateTime<O> {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, duration: StdDuration) -> Self::Output {
         let (is_previous_day, time) = self.time.adjusting_sub_std(duration);
 
@@ -1224,6 +1236,9 @@ impl From<DateTime<offset_kind::Fixed>> for SystemTime {
     feature = "wasm-bindgen"
 ))]
 impl From<js_sys::Date> for DateTime<offset_kind::Fixed> {
+    /// # Panics
+    ///
+    /// This may panic if the timestamp can not be represented.
     fn from(js_date: js_sys::Date) -> Self {
         // get_time() returns milliseconds
         let timestamp_nanos = (js_date.get_time() * Nanosecond::per(Millisecond) as f64) as i128;

diff --git a/time/src/duration.rs b/time/src/duration.rs
@@ -380,6 +380,10 @@ impl Duration {
     /// assert_eq!(Duration::new(-1, 0), (-1).seconds());
     /// assert_eq!(Duration::new(1, 2_000_000_000), 3.seconds());
     /// ```
+    ///
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     pub const fn new(mut seconds: i64, mut nanoseconds: i32) -> Self {
         seconds = expect_opt!(
             seconds.checked_add(nanoseconds as i64 / Nanosecond::per(Second) as i64),
@@ -431,6 +435,10 @@ impl Duration {
     /// # use time::{Duration, ext::NumericalDuration};
     /// assert_eq!(Duration::weeks(1), 604_800.seconds());
     /// ```
+    ///
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     pub const fn weeks(weeks: i64) -> Self {
         Self::seconds(expect_opt!(
             weeks.checked_mul(Second::per(Week) as _),
@@ -445,6 +453,10 @@ impl Duration {
     /// # use time::{Duration, ext::NumericalDuration};
     /// assert_eq!(Duration::days(1), 86_400.seconds());
     /// ```
+    ///
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     pub const fn days(days: i64) -> Self {
         Self::seconds(expect_opt!(
             days.checked_mul(Second::per(Day) as _),
@@ -459,6 +471,10 @@ impl Duration {
     /// # use time::{Duration, ext::NumericalDuration};
     /// assert_eq!(Duration::hours(1), 3_600.seconds());
     /// ```
+    ///
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     pub const fn hours(hours: i64) -> Self {
         Self::seconds(expect_opt!(
             hours.checked_mul(Second::per(Hour) as _),
@@ -473,6 +489,10 @@ impl Duration {
     /// # use time::{Duration, ext::NumericalDuration};
     /// assert_eq!(Duration::minutes(1), 60.seconds());
     /// ```
+    ///
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     pub const fn minutes(minutes: i64) -> Self {
         Self::seconds(expect_opt!(
             minutes.checked_mul(Second::per(Minute) as _),
@@ -1263,6 +1283,9 @@ impl TryFrom<Duration> for StdDuration {
 impl Add for Duration {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, rhs: Self) -> Self::Output {
         self.checked_add(rhs)
             .expect("overflow when adding durations")
@@ -1272,6 +1295,9 @@ impl Add for Duration {
 impl Add<StdDuration> for Duration {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn add(self, std_duration: StdDuration) -> Self::Output {
         self + Self::try_from(std_duration)
             .expect("overflow converting `std::time::Duration` to `time::Duration`")
@@ -1289,6 +1315,9 @@ impl Add<Duration> for StdDuration {
 impl_add_assign!(Duration: Self, StdDuration);
 
 impl AddAssign<Duration> for StdDuration {
+    /// # Panics
+    ///
+    /// This may panic if the resulting addition cannot be represented.
     fn add_assign(&mut self, rhs: Duration) {
         *self = (*self + rhs).try_into().expect(
             "Cannot represent a resulting duration in std. Try `let x = x + rhs;`, which will \
@@ -1308,6 +1337,9 @@ impl Neg for Duration {
 impl Sub for Duration {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, rhs: Self) -> Self::Output {
         self.checked_sub(rhs)
             .expect("overflow when subtracting durations")
@@ -1317,6 +1349,9 @@ impl Sub for Duration {
 impl Sub<StdDuration> for Duration {
     type Output = Self;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, rhs: StdDuration) -> Self::Output {
         self - Self::try_from(rhs)
             .expect("overflow converting `std::time::Duration` to `time::Duration`")
@@ -1326,6 +1361,9 @@ impl Sub<StdDuration> for Duration {
 impl Sub<Duration> for StdDuration {
     type Output = Duration;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, rhs: Duration) -> Self::Output {
         Duration::try_from(self)
             .expect("overflow converting `std::time::Duration` to `time::Duration`")
@@ -1336,6 +1374,9 @@ impl Sub<Duration> for StdDuration {
 impl_sub_assign!(Duration: Self, StdDuration);
 
 impl SubAssign<Duration> for StdDuration {
+    /// # Panics
+    ///
+    /// This may panic if the resulting subtraction can not be represented.
     fn sub_assign(&mut self, rhs: Duration) {
         *self = (*self - rhs).try_into().expect(
             "Cannot represent a resulting duration in std. Try `let x = x - rhs;`, which will \

diff --git a/time/src/ext.rs b/time/src/ext.rs
@@ -219,27 +219,39 @@ impl NumericalStdDuration for u64 {
         StdDuration::from_secs(self)
     }
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn std_minutes(self) -> StdDuration {
         StdDuration::from_secs(
             self.checked_mul(Second::per(Minute) as Self)
                 .expect("overflow constructing `time::Duration`"),
         )
     }
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn std_hours(self) -> StdDuration {
         StdDuration::from_secs(
             self.checked_mul(Second::per(Hour) as Self)
                 .expect("overflow constructing `time::Duration`"),
         )
     }
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn std_days(self) -> StdDuration {
         StdDuration::from_secs(
             self.checked_mul(Second::per(Day) as Self)
                 .expect("overflow constructing `time::Duration`"),
         )
     }
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn std_weeks(self) -> StdDuration {
         StdDuration::from_secs(
             self.checked_mul(Second::per(Week) as Self)
@@ -249,41 +261,65 @@ impl NumericalStdDuration for u64 {
 }
 
 impl NumericalStdDuration for f64 {
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_nanoseconds(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos(self as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_microseconds(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Microsecond) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_milliseconds(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Millisecond) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_seconds(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Second) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_minutes(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Minute) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_hours(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Hour) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_days(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Day) as Self) as _)
     }
 
+    /// # Panics
+    ///
+    /// This will panic if self is negative.
     fn std_weeks(self) -> StdDuration {
         assert!(self >= 0.);
         StdDuration::from_nanos((self * Nanosecond::per(Week) as Self) as _)

diff --git a/time/src/instant.rs b/time/src/instant.rs
@@ -129,6 +129,9 @@ impl From<Instant> for StdInstant {
 impl Sub for Instant {
     type Output = Duration;
 
+    /// # Panics
+    ///
+    /// This may panic if an overflow occurs.
     fn sub(self, other: Self) -> Self::Output {
         match self.0.cmp(&other.0) {
             Ordering::Equal => Duration::ZERO,