From 9278b4c67284db95990673f26934b9d1d5af2e77 Mon Sep 17 00:00:00 2001
From: Jim Turner <git@turner.link>
Date: Mon, 1 Mar 2021 16:09:41 -0500
Subject: [PATCH 1/2] Document panicking cases for integer division

The panic on division by zero is expected, but the panic on overflow
is somewhat surprising (since most arithmetic operations panic on
overflow only when `debug_assertions` is enabled). As a result, it's
helpful to document this behavior.
---
 library/core/src/ops/arith.rs | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/library/core/src/ops/arith.rs b/library/core/src/ops/arith.rs
index 92090d8e6fc..da0f038e44e 100644
--- a/library/core/src/ops/arith.rs
+++ b/library/core/src/ops/arith.rs
@@ -456,9 +456,13 @@ pub trait Div<Rhs = Self> {
 }
 
 macro_rules! div_impl_integer {
-    ($($t:ty)*) => ($(
+    ($(($($t:ty)*) => $panic:expr),*) => ($($(
         /// This operation rounds towards zero, truncating any
         /// fractional part of the exact result.
+        ///
+        /// # Panics
+        ///
+        #[doc = $panic]
         #[stable(feature = "rust1", since = "1.0.0")]
         impl Div for $t {
             type Output = $t;
@@ -468,10 +472,13 @@ fn div(self, other: $t) -> $t { self / other }
         }
 
         forward_ref_binop! { impl Div, div for $t, $t }
-    )*)
+    )*)*)
 }
 
-div_impl_integer! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
+div_impl_integer! {
+    (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.",
+    (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or the division results in overflow."
+}
 
 macro_rules! div_impl_float {
     ($($t:ty)*) => ($(

From b45855032b3aad0ea0a48894f56cb9bb8fa361f2 Mon Sep 17 00:00:00 2001
From: Jim Turner <git@turner.link>
Date: Mon, 1 Mar 2021 16:19:59 -0500
Subject: [PATCH 2/2] Document panicking cases for integer remainder

The panic when the right operand is `0` is expected, but the
overflow-related panic (which occurs only for `MIN % -1`) is somewhat
surprising for two reasons: a return value of `0` would be reasonable
in this case, and, for most arithmetic operations, overflow results in
panic only when `debug_assertions` is enabled. As a result, it's
helpful to document this behavior.
---
 library/core/src/ops/arith.rs | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/library/core/src/ops/arith.rs b/library/core/src/ops/arith.rs
index da0f038e44e..a0577b287ce 100644
--- a/library/core/src/ops/arith.rs
+++ b/library/core/src/ops/arith.rs
@@ -556,9 +556,13 @@ pub trait Rem<Rhs = Self> {
 }
 
 macro_rules! rem_impl_integer {
-    ($($t:ty)*) => ($(
+    ($(($($t:ty)*) => $panic:expr),*) => ($($(
         /// This operation satisfies `n % d == n - (n / d) * d`. The
         /// result has the same sign as the left operand.
+        ///
+        /// # Panics
+        ///
+        #[doc = $panic]
         #[stable(feature = "rust1", since = "1.0.0")]
         impl Rem for $t {
             type Output = $t;
@@ -568,10 +572,13 @@ fn rem(self, other: $t) -> $t { self % other }
         }
 
         forward_ref_binop! { impl Rem, rem for $t, $t }
-    )*)
+    )*)*)
 }
 
-rem_impl_integer! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
+rem_impl_integer! {
+    (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.",
+    (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or if `self / other` results in overflow."
+}
 
 macro_rules! rem_impl_float {
     ($($t:ty)*) => ($(