Improve documentation of rounding functions

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();

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();

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,27 +136,34 @@ 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 {
  Ratio::from_integer((self.numer + self.denom - One::one()) / self.denom)
  }
  }
 
+ /// 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);