Merge pull request #332 from ocstl/master

Fix checked operations documentation.

Author: cuviper

src/ops/checked.rs

@@ -1,7 +1,6 @@
 use core::ops::{Add, Div, Mul, Rem, Shl, Shr, Sub};
 
-/// Performs addition that returns `None` instead of wrapping around on
-/// overflow.
+/// Performs addition, returning `None` if overflow occurred.
 pub trait CheckedAdd: Sized + Add<Self, Output = Self> {
     /// Adds two numbers, checking for overflow. If overflow happens, `None` is
     /// returned.
@@ -33,9 +32,9 @@ checked_impl!(CheckedAdd, checked_add, i64);
 checked_impl!(CheckedAdd, checked_add, isize);
 checked_impl!(CheckedAdd, checked_add, i128);
 
-/// Performs subtraction that returns `None` instead of wrapping around on underflow.
+/// Performs subtraction, returning `None` if overflow occurred.
 pub trait CheckedSub: Sized + Sub<Self, Output = Self> {
-    /// Subtracts two numbers, checking for underflow. If underflow happens,
+    /// Subtracts two numbers, checking for overflow. If overflow happens,
     /// `None` is returned.
     fn checked_sub(&self, v: &Self) -> Option<Self>;
 }
@@ -54,11 +53,10 @@ checked_impl!(CheckedSub, checked_sub, i64);
 checked_impl!(CheckedSub, checked_sub, isize);
 checked_impl!(CheckedSub, checked_sub, i128);
 
-/// Performs multiplication that returns `None` instead of wrapping around on underflow or
-/// overflow.
+/// Performs multiplication, returning `None` if overflow occurred.
 pub trait CheckedMul: Sized + Mul<Self, Output = Self> {
-    /// Multiplies two numbers, checking for underflow or overflow. If underflow
-    /// or overflow happens, `None` is returned.
+    /// Multiplies two numbers, checking for overflow. If overflow happens,
+    /// `None` is returned.
     fn checked_mul(&self, v: &Self) -> Option<Self>;
 }
 
@@ -76,10 +74,10 @@ checked_impl!(CheckedMul, checked_mul, i64);
 checked_impl!(CheckedMul, checked_mul, isize);
 checked_impl!(CheckedMul, checked_mul, i128);
 
-/// Performs division that returns `None` instead of panicking on division by zero and instead of
-/// wrapping around on underflow and overflow.
+/// Performs division, returning `None` on division by zero or if overflow
+/// occurred.
 pub trait CheckedDiv: Sized + Div<Self, Output = Self> {
-    /// Divides two numbers, checking for underflow, overflow and division by
+    /// Divides two numbers, checking for overflow and division by
     /// zero. If any of that happens, `None` is returned.
     fn checked_div(&self, v: &Self) -> Option<Self>;
 }
@@ -98,11 +96,11 @@ checked_impl!(CheckedDiv, checked_div, i64);
 checked_impl!(CheckedDiv, checked_div, isize);
 checked_impl!(CheckedDiv, checked_div, i128);
 
-/// Performs an integral remainder that returns `None` instead of panicking on division by zero and
-/// instead of wrapping around on underflow and overflow.
+/// Performs integral remainder, returning `None` on division by zero or if
+/// overflow occurred.
 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.
+    /// Finds the remainder of dividing two numbers, checking for overflow and
+    /// division by zero. If any of that happens, `None` is returned.
     ///
     /// # Examples
     ///
@@ -148,7 +146,7 @@ macro_rules! checked_impl_unary {
     };
 }
 
-/// Performs negation that returns `None` if the result can't be represented.
+/// Performs negation, returning `None` if the result can't be represented.
 pub trait CheckedNeg: Sized {
     /// Negates a number, returning `None` for results that can't be represented, like signed `MIN`
     /// values that can't be positive, or non-zero unsigned values that can't be negative.
@@ -183,8 +181,8 @@ checked_impl_unary!(CheckedNeg, checked_neg, i64);
 checked_impl_unary!(CheckedNeg, checked_neg, isize);
 checked_impl_unary!(CheckedNeg, checked_neg, i128);
 
-/// Performs a left shift that returns `None` on shifts larger than
-/// or equal to the type width.
+/// Performs shift left, returning `None` on shifts larger than or equal to
+/// the type width.
 pub trait CheckedShl: Sized + Shl<u32, Output = Self> {
     /// Checked shift left. Computes `self << rhs`, returning `None`
     /// if `rhs` is larger than or equal to the number of bits in `self`.
@@ -227,8 +225,8 @@ checked_shift_impl!(CheckedShl, checked_shl, i64);
 checked_shift_impl!(CheckedShl, checked_shl, isize);
 checked_shift_impl!(CheckedShl, checked_shl, i128);
 
-/// Performs a right shift that returns `None` on shifts larger than
-/// or equal to the type width.
+/// Performs shift right, returning `None` on shifts larger than or equal to
+/// the type width.
 pub trait CheckedShr: Sized + Shr<u32, Output = Self> {
     /// Checked shift right. Computes `self >> rhs`, returning `None`
     /// if `rhs` is larger than or equal to the number of bits in `self`.

src/ops/euclid.rs

@@ -136,15 +136,16 @@ impl Euclid for f64 {
 }
 
 pub trait CheckedEuclid: Euclid {
-    /// Performs euclid division that returns `None` instead of panicking on division by zero
-    /// and instead of wrapping around on underflow and overflow.
+    /// Performs euclid division, returning `None` on division by zero or if
+    /// overflow occurred.
     fn checked_div_euclid(&self, v: &Self) -> Option<Self>;
 
-    /// Finds the euclid remainder of dividing two numbers, checking for underflow, overflow and
-    /// division by zero. If any of that happens, `None` is returned.
+    /// Finds the euclid remainder of dividing two numbers, returning `None` on
+    /// division by zero or if overflow occurred.
     fn checked_rem_euclid(&self, v: &Self) -> Option<Self>;
 
-    /// Returns both the quotient and remainder from checked Euclidean division.
+    /// Returns both the quotient and remainder from checked Euclidean division,
+    /// returning `None` on division by zero or if overflow occurred.
     ///
     /// By default, it internally calls both `CheckedEuclid::checked_div_euclid` and `CheckedEuclid::checked_rem_euclid`,
     /// but it can be overridden in order to implement some optimization.