Document CheckedRem and CheckedNeg

src/ops/checked.rs

@@ -90,8 +90,28 @@ checked_impl!(CheckedDiv, checked_div, i32);
 checked_impl!(CheckedDiv, checked_div, i64);
 checked_impl!(CheckedDiv, checked_div, isize);
 
-// CheckedRem
+/// Performs an integral remainder that returns `None` instead of panicking on division by zero and
+/// instead of wrapping around on underflow and overflow.
 pub trait CheckedRem: Sized + Rem<Self, Output = Self> {
+    /// Finds the remainder of dividing two numbers, checking for underflow, overflow and division
+    /// by zero. If any of that happens, `None` is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use num_traits::CheckedRem;
+    /// use std::i32::MIN;
+    ///
+    /// assert_eq!(CheckedRem::checked_rem(&10, &7), Some(3));
+    /// assert_eq!(CheckedRem::checked_rem(&10, &-7), Some(3));
+    /// assert_eq!(CheckedRem::checked_rem(&-10, &7), Some(-3));
+    /// assert_eq!(CheckedRem::checked_rem(&-10, &-7), Some(-3));
+    ///
+    /// assert_eq!(CheckedRem::checked_rem(&10, &0), None);
+    ///
+    /// assert_eq!(CheckedRem::checked_rem(&MIN, &1), Some(0));
+    /// assert_eq!(CheckedRem::checked_rem(&MIN, &-1), None);
+    /// ```
     fn checked_rem(&self, v: &Self) -> Option<Self>;
 }
 
@@ -118,7 +138,24 @@ macro_rules! checked_impl_unary {
     }
 }
 
+/// Performs negation that returns `None` if the result can't be represented.
 pub trait CheckedNeg: Sized {
+    /// Negates a number, returning `None` for results taht can't be represented, like signed `MIN`
+    /// values that can't be positive, or non-zero unsigned values that can't be negative.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use num_traits::CheckedNeg;
+    /// use std::i32::MIN;
+    ///
+    /// assert_eq!(CheckedNeg::checked_neg(&1_i32), Some(-1));
+    /// assert_eq!(CheckedNeg::checked_neg(&-1_i32), Some(1));
+    /// assert_eq!(CheckedNeg::checked_neg(&MIN), None);
+    ///
+    /// assert_eq!(CheckedNeg::checked_neg(&0_u32), Some(0));
+    /// assert_eq!(CheckedNeg::checked_neg(&1_u32), None);
+    /// ```
     fn checked_neg(&self) -> Option<Self>;
 }