Improve documentation of rounding functions

3 files changed, 53 insertions, 43 deletions

diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs
index 82745663e0c..d4cf10b384f 100644
--- a/src/libcore/num/f32.rs
+++ b/src/libcore/num/f32.rs
@@ -117,23 +117,23 @@ impl Float for f32 {
     #[inline]
     fn neg_zero() -> f32 { -0.0 }
 
-    /// Returns `true` if the number is NaN
+    /// Returns `true` if the number is NaN.
     #[inline]
     fn is_nan(self) -> bool { self != self }
 
-    /// Returns `true` if the number is infinite
+    /// Returns `true` if the number is infinite.
     #[inline]
     fn is_infinite(self) -> bool {
         self == Float::infinity() || self == Float::neg_infinity()
     }
 
-    /// Returns `true` if the number is neither infinite or NaN
+    /// Returns `true` if the number is neither infinite or NaN.
     #[inline]
     fn is_finite(self) -> bool {
         !(self.is_nan() || self.is_infinite())
     }
 
-    /// Returns `true` if the number is neither zero, infinite, subnormal or NaN
+    /// Returns `true` if the number is neither zero, infinite, subnormal or NaN.
     #[inline]
     fn is_normal(self) -> bool {
         self.classify() == FPNormal
@@ -195,25 +195,25 @@ impl Float for f32 {
         (mantissa as u64, exponent, sign)
     }
 
-    /// Round half-way cases toward `NEG_INFINITY`
+    /// Rounds towards minus infinity.
     #[inline]
     fn floor(self) -> f32 {
         unsafe { intrinsics::floorf32(self) }
     }
 
-    /// Round half-way cases toward `INFINITY`
+    /// Rounds towards plus infinity.
     #[inline]
     fn ceil(self) -> f32 {
         unsafe { intrinsics::ceilf32(self) }
     }
 
-    /// Round half-way cases away from `0.0`
+    /// Rounds to nearest integer. Rounds half-way cases away from zero.
     #[inline]
     fn round(self) -> f32 {
         unsafe { intrinsics::roundf32(self) }
     }
 
-    /// The integer part of the number (rounds towards `0.0`)
+    /// Returns the integer part of the number (rounds towards zero).
     #[inline]
     fn trunc(self) -> f32 {
         unsafe { intrinsics::truncf32(self) }
@@ -236,7 +236,7 @@ impl Float for f32 {
         unsafe { intrinsics::fmaf32(self, a, b) }
     }
 
-    /// The reciprocal (multiplicative inverse) of the number
+    /// Returns the reciprocal (multiplicative inverse) of the number.
     #[inline]
     fn recip(self) -> f32 { 1.0 / self }
 
@@ -325,45 +325,45 @@ impl Float for f32 {
     #[inline]
     fn ln_10() -> f32 { consts::LN_10 }
 
-    /// Returns the exponential of the number
+    /// Returns the exponential of the number.
     #[inline]
     fn exp(self) -> f32 {
         unsafe { intrinsics::expf32(self) }
     }
 
-    /// Returns 2 raised to the power of the number
+    /// Returns 2 raised to the power of the number.
     #[inline]
     fn exp2(self) -> f32 {
         unsafe { intrinsics::exp2f32(self) }
     }
 
-    /// Returns the natural logarithm of the number
+    /// Returns the natural logarithm of the number.
     #[inline]
     fn ln(self) -> f32 {
         unsafe { intrinsics::logf32(self) }
     }
 
-    /// Returns the logarithm of the number with respect to an arbitrary base
+    /// Returns the logarithm of the number with respect to an arbitrary base.
     #[inline]
     fn log(self, base: f32) -> f32 { self.ln() / base.ln() }
 
-    /// Returns the base 2 logarithm of the number
+    /// Returns the base 2 logarithm of the number.
     #[inline]
     fn log2(self) -> f32 {
         unsafe { intrinsics::log2f32(self) }
     }
 
-    /// Returns the base 10 logarithm of the number
+    /// Returns the base 10 logarithm of the number.
     #[inline]
     fn log10(self) -> f32 {
         unsafe { intrinsics::log10f32(self) }
     }
 
-    /// Converts to degrees, assuming the number is in radians
+    /// Converts to degrees, assuming the number is in radians.
     #[inline]
     fn to_degrees(self) -> f32 { self * (180.0f32 / Float::pi()) }
 
-    /// Converts to radians, assuming the number is in degrees
+    /// Converts to radians, assuming the number is in degrees.
     #[inline]
     fn to_radians(self) -> f32 {
         let value: f32 = Float::pi();
diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs
index a3a82aeec5e..a3ae8e7c79e 100644
--- a/src/libcore/num/f64.rs
+++ b/src/libcore/num/f64.rs
@@ -123,23 +123,23 @@ impl Float for f64 {
     #[inline]
     fn neg_zero() -> f64 { -0.0 }
 
-    /// Returns `true` if the number is NaN
+    /// Returns `true` if the number is NaN.
     #[inline]
     fn is_nan(self) -> bool { self != self }
 
-    /// Returns `true` if the number is infinite
+    /// Returns `true` if the number is infinite.
     #[inline]
     fn is_infinite(self) -> bool {
         self == Float::infinity() || self == Float::neg_infinity()
     }
 
-    /// Returns `true` if the number is neither infinite or NaN
+    /// Returns `true` if the number is neither infinite or NaN.
     #[inline]
     fn is_finite(self) -> bool {
         !(self.is_nan() || self.is_infinite())
     }
 
-    /// Returns `true` if the number is neither zero, infinite, subnormal or NaN
+    /// Returns `true` if the number is neither zero, infinite, subnormal or NaN.
     #[inline]
     fn is_normal(self) -> bool {
         self.classify() == FPNormal
@@ -201,25 +201,25 @@ impl Float for f64 {
         (mantissa, exponent, sign)
     }
 
-    /// Round half-way cases toward `NEG_INFINITY`
+    /// Rounds towards minus infinity.
     #[inline]
     fn floor(self) -> f64 {
         unsafe { intrinsics::floorf64(self) }
     }
 
-    /// Round half-way cases toward `INFINITY`
+    /// Rounds towards plus infinity.
     #[inline]
     fn ceil(self) -> f64 {
         unsafe { intrinsics::ceilf64(self) }
     }
 
-    /// Round half-way cases away from `0.0`
+    /// Rounds to nearest integer. Rounds half-way cases away from zero.
     #[inline]
     fn round(self) -> f64 {
         unsafe { intrinsics::roundf64(self) }
     }
 
-    /// The integer part of the number (rounds towards `0.0`)
+    /// Returns the integer part of the number (rounds towards zero).
     #[inline]
     fn trunc(self) -> f64 {
         unsafe { intrinsics::truncf64(self) }
@@ -242,7 +242,7 @@ impl Float for f64 {
         unsafe { intrinsics::fmaf64(self, a, b) }
     }
 
-    /// The reciprocal (multiplicative inverse) of the number
+    /// Returns the reciprocal (multiplicative inverse) of the number.
     #[inline]
     fn recip(self) -> f64 { 1.0 / self }
 
@@ -332,46 +332,45 @@ impl Float for f64 {
     #[inline]
     fn ln_10() -> f64 { consts::LN_10 }
 
-    /// Returns the exponential of the number
+    /// Returns the exponential of the number.
     #[inline]
     fn exp(self) -> f64 {
         unsafe { intrinsics::expf64(self) }
     }
 
-    /// Returns 2 raised to the power of the number
+    /// Returns 2 raised to the power of the number.
     #[inline]
     fn exp2(self) -> f64 {
         unsafe { intrinsics::exp2f64(self) }
     }
 
-    /// Returns the natural logarithm of the number
+    /// Returns the natural logarithm of the number.
     #[inline]
     fn ln(self) -> f64 {
         unsafe { intrinsics::logf64(self) }
     }
 
-    /// Returns the logarithm of the number with respect to an arbitrary base
+    /// Returns the logarithm of the number with respect to an arbitrary base.
     #[inline]
     fn log(self, base: f64) -> f64 { self.ln() / base.ln() }
 
-    /// Returns the base 2 logarithm of the number
+    /// Returns the base 2 logarithm of the number.
     #[inline]
     fn log2(self) -> f64 {
         unsafe { intrinsics::log2f64(self) }
     }
 
-    /// Returns the base 10 logarithm of the number
+    /// Returns the base 10 logarithm of the number.
     #[inline]
     fn log10(self) -> f64 {
         unsafe { intrinsics::log10f64(self) }
     }
 
-
-    /// Converts to degrees, assuming the number is in radians
+    /// Converts to degrees, assuming the number is in radians.
     #[inline]
     fn to_degrees(self) -> f64 { self * (180.0f64 / Float::pi()) }
 
-    /// Converts to radians, assuming the number is in degrees
+    /// Converts to radians, assuming the number is in degrees.
     #[inline]
     fn to_radians(self) -> f64 {
         let value: f64 = Float::pi();
diff --git a/src/libnum/rational.rs b/src/libnum/rational.rs
index a279ede6fa5..e0f6b4fb9af 100644
--- a/src/libnum/rational.rs
+++ b/src/libnum/rational.rs
@@ -38,13 +38,13 @@ pub type BigRational = Ratio<BigInt>;
 
 impl<T: Clone + Integer + PartialOrd>
     Ratio<T> {
-    /// Create a ratio representing the integer `t`.
+    /// Creates a ratio representing the integer `t`.
     #[inline]
     pub fn from_integer(t: T) -> Ratio<T> {
         Ratio::new_raw(t, One::one())
     }
 
-    /// Create a ratio without checking for `denom == 0` or reducing.
+    /// Creates a ratio without checking for `denom == 0` or reducing.
     #[inline]
     pub fn new_raw(numer: T, denom: T) -> Ratio<T> {
         Ratio { numer: numer, denom: denom }
@@ -61,7 +61,7 @@ impl<T: Clone + Integer + PartialOrd>
         ret
     }
 
-    /// Convert to an integer.
+    /// Converts to an integer.
     #[inline]
     pub fn to_integer(&self) -> T {
         self.trunc().numer
@@ -79,7 +79,7 @@ impl<T: Clone + Integer + PartialOrd>
         &self.denom
     }
 
-    /// Return true if the rational number is an integer (denominator is 1).
+    /// Returns true if the rational number is an integer (denominator is 1).
     #[inline]
     pub fn is_integer(&self) -> bool {
         self.denom == One::one()
@@ -103,19 +103,21 @@ impl<T: Clone + Integer + PartialOrd>
         }
     }
 
-    /// Return a `reduce`d copy of self.
+    /// Returns a `reduce`d copy of self.
     pub fn reduced(&self) -> Ratio<T> {
         let mut ret = self.clone();
         ret.reduce();
         ret
     }
 
-    /// Return the reciprocal
+    /// Returns the reciprocal.
     #[inline]
     pub fn recip(&self) -> Ratio<T> {
         Ratio::new_raw(self.denom.clone(), self.numer.clone())
     }
 
+    /// Rounds towards minus infinity.
+    #[inline]
     pub fn floor(&self) -> Ratio<T> {
         if *self < Zero::zero() {
             Ratio::from_integer((self.numer - self.denom + One::one()) / self.denom)
@@ -124,6 +126,8 @@ impl<T: Clone + Integer + PartialOrd>
         }
     }
 
+    /// Rounds towards plus infinity.
+    #[inline]
     pub fn ceil(&self) -> Ratio<T> {
         if *self < Zero::zero() {
             Ratio::from_integer(self.numer / self.denom)
@@ -132,8 +136,12 @@ impl<T: Clone + Integer + PartialOrd>
         }
     }
 
+    /// Rounds to the nearest integer. Rounds half-way cases away from zero.
+    ///
+    /// Note: This function is currently broken and always rounds away from zero.
     #[inline]
     pub fn round(&self) -> Ratio<T> {
+        // FIXME(#15826)
         if *self < Zero::zero() {
             Ratio::from_integer((self.numer - self.denom + One::one()) / self.denom)
         } else {
@@ -141,18 +149,21 @@ impl<T: Clone + Integer + PartialOrd>
         }
     }
 
+    /// Rounds towards zero.
     #[inline]
     pub fn trunc(&self) -> Ratio<T> {
         Ratio::from_integer(self.numer / self.denom)
     }
 
+    ///Returns the fractional part of a number.
+    #[inline]
     pub fn fract(&self) -> Ratio<T> {
         Ratio::new_raw(self.numer % self.denom, self.denom.clone())
     }
 }
 
 impl Ratio<BigInt> {
-    /// Converts a float into a rational number
+    /// Converts a float into a rational number.
     pub fn from_float<T: Float>(f: T) -> Option<BigRational> {
         if !f.is_finite() {
             return None;
@@ -328,7 +339,7 @@ impl<T: ToStrRadix> ToStrRadix for Ratio<T> {
 
 impl<T: FromStr + Clone + Integer + PartialOrd>
     FromStr for Ratio<T> {
-    /// Parses `numer/denom` or just `numer`
+    /// Parses `numer/denom` or just `numer`.
     fn from_str(s: &str) -> Option<Ratio<T>> {
         let mut split = s.splitn('/', 1);