Merge pull request #171 from Schultzer/add-docs

Add missing docs

Author: alexcrichton

src/math/acos.rs

@@ -55,6 +55,11 @@ fn r(z: f64) -> f64 {
     p / q
 }
 
+/// Arccosine (f64)
+///
+/// Computes the inverse cosine (arc cosine) of the input value.
+/// Arguments must be in the range -1 to 1.
+/// Returns values in radians, in the range of 0 to pi.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn acos(x: f64) -> f64 {

src/math/acosf.rs

@@ -29,6 +29,11 @@ fn r(z: f32) -> f32 {
     p / q
 }
 
+/// Arccosine (f32)
+///
+/// Computes the inverse cosine (arc cosine) of the input value.
+/// Arguments must be in the range -1 to 1.
+/// Returns values in radians, in the range of 0 to pi.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn acosf(x: f32) -> f32 {

src/math/acosh.rs

@@ -2,7 +2,11 @@ use super::{log, log1p, sqrt};
 
 const LN2: f64 = 0.693147180559945309417232121458176568; /* 0x3fe62e42,  0xfefa39ef*/
 
-/* acosh(x) = log(x + sqrt(x*x-1)) */
+/// Inverse hyperbolic cosine (f64)
+///
+/// Calculates the inverse hyperbolic cosine of `x`.
+/// Is defined as `log(x + sqrt(x*x-1))`.
+/// `x` must be a number greater than or equal to 1.
 pub fn acosh(x: f64) -> f64 {
     let u = x.to_bits();
     let e = ((u >> 52) as usize) & 0x7ff;

src/math/acoshf.rs

@@ -2,7 +2,11 @@ use super::{log1pf, logf, sqrtf};
 
 const LN2: f32 = 0.693147180559945309417232121458176568;
 
-/* acosh(x) = log(x + sqrt(x*x-1)) */
+/// Inverse hyperbolic cosine (f32)
+///
+/// Calculates the inverse hyperbolic cosine of `x`.
+/// Is defined as `log(x + sqrt(x*x-1))`.
+/// `x` must be a number greater than or equal to 1.
 pub fn acoshf(x: f32) -> f32 {
     let u = x.to_bits();
     let a = u & 0x7fffffff;

src/math/asin.rs

@@ -62,6 +62,11 @@ fn comp_r(z: f64) -> f64 {
     p / q
 }
 
+/// Arcsine (f64)
+///
+/// Computes the inverse sine (arc sine) of the argument `x`.
+/// Arguments to asin must be in the range -1 to 1.
+/// Returns values in radians, in the range of -pi/2 to pi/2.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn asin(mut x: f64) -> f64 {

src/math/asinf.rs

@@ -31,6 +31,11 @@ fn r(z: f32) -> f32 {
     p / q
 }
 
+/// Arcsine (f32)
+///
+/// Computes the inverse sine (arc sine) of the argument `x`.
+/// Arguments to asin must be in the range -1 to 1.
+/// Returns values in radians, in the range of -pi/2 to pi/2.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn asinf(mut x: f32) -> f32 {

src/math/asinh.rs

@@ -3,6 +3,10 @@ use super::{log, log1p, sqrt};
 const LN2: f64 = 0.693147180559945309417232121458176568; /* 0x3fe62e42,  0xfefa39ef*/
 
 /* asinh(x) = sign(x)*log(|x|+sqrt(x*x+1)) ~= x - x^3/6 + o(x^5) */
+/// Inverse hyperbolic sine (f64)
+///
+/// Calculates the inverse hyperbolic sine of `x`.
+/// Is defined as `sgn(x)*log(|x|+sqrt(x*x+1))`.
 pub fn asinh(mut x: f64) -> f64 {
     let mut u = x.to_bits();
     let e = ((u >> 52) as usize) & 0x7ff;

src/math/asinhf.rs

@@ -3,6 +3,10 @@ use super::{log1pf, logf, sqrtf};
 const LN2: f32 = 0.693147180559945309417232121458176568;
 
 /* asinh(x) = sign(x)*log(|x|+sqrt(x*x+1)) ~= x - x^3/6 + o(x^5) */
+/// Inverse hyperbolic sine (f32)
+///
+/// Calculates the inverse hyperbolic sine of `x`.
+/// Is defined as `sgn(x)*log(|x|+sqrt(x*x+1))`.
 pub fn asinhf(mut x: f32) -> f32 {
     let u = x.to_bits();
     let i = u & 0x7fffffff;

src/math/atan.rs

@@ -60,6 +60,10 @@ const AT: [f64; 11] = [
     1.62858201153657823623e-02,  /* 0x3F90AD3A, 0xE322DA11 */
 ];
 
+/// Arctangent (f64)
+///
+/// Computes the inverse tangent (arc tangent) of the input value.
+/// Returns a value in radians, in the range of -pi/2 to pi/2.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn atan(x: f64) -> f64 {

src/math/atan2.rs

@@ -43,6 +43,11 @@ use super::fabs;
 const PI: f64 = 3.1415926535897931160E+00; /* 0x400921FB, 0x54442D18 */
 const PI_LO: f64 = 1.2246467991473531772E-16; /* 0x3CA1A626, 0x33145C07 */
 
+/// Arctangent of y/x (f64)
+///
+/// Computes the inverse tangent (arc tangent) of `y/x`.
+/// Produces the correct result even for angles near pi/2 or -pi/2 (that is, when `x` is near 0).
+/// Returns a value in radians, in the range of -pi to pi.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn atan2(y: f64, x: f64) -> f64 {

src/math/atan2f.rs

@@ -19,6 +19,11 @@ use super::fabsf;
 const PI: f32 = 3.1415927410e+00; /* 0x40490fdb */
 const PI_LO: f32 = -8.7422776573e-08; /* 0xb3bbbd2e */
 
+/// Arctangent of y/x (f32)
+///
+/// Computes the inverse tangent (arc tangent) of `y/x`.
+/// Produces the correct result even for angles near pi/2 or -pi/2 (that is, when `x` is near 0).
+/// Returns a value in radians, in the range of -pi to pi.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn atan2f(y: f32, x: f32) -> f32 {

src/math/atanf.rs

@@ -37,6 +37,10 @@ const A_T: [f32; 5] = [
     6.1687607318e-02,
 ];
 
+/// Arctangent (f32)
+///
+/// Computes the inverse tangent (arc tangent) of the input value.
+/// Returns a value in radians, in the range of -pi/2 to pi/2.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn atanf(mut x: f32) -> f32 {

src/math/atanh.rs

@@ -1,6 +1,10 @@
 use super::log1p;
 
 /* atanh(x) = log((1+x)/(1-x))/2 = log1p(2x/(1-x))/2 ~= x + x^3/3 + o(x^5) */
+/// Inverse hyperbolic tangent (f64)
+///
+/// Calculates the inverse hyperbolic tangent of `x`.
+/// Is defined as `log((1+x)/(1-x))/2 = log1p(2x/(1-x))/2`.
 pub fn atanh(x: f64) -> f64 {
     let u = x.to_bits();
     let e = ((u >> 52) as usize) & 0x7ff;

src/math/atanhf.rs

@@ -1,6 +1,10 @@
 use super::log1pf;
 
 /* atanh(x) = log((1+x)/(1-x))/2 = log1p(2x/(1-x))/2 ~= x + x^3/3 + o(x^5) */
+/// Inverse hyperbolic tangent (f32)
+///
+/// Calculates the inverse hyperbolic tangent of `x`.
+/// Is defined as `log((1+x)/(1-x))/2 = log1p(2x/(1-x))/2`.
 pub fn atanhf(mut x: f32) -> f32 {
     let mut u = x.to_bits();
     let sign = (u >> 31) != 0;

src/math/cbrt.rs

@@ -27,6 +27,9 @@ const P2: f64 = 1.621429720105354466140; /* 0x3ff9f160, 0x4a49d6c2 */
 const P3: f64 = -0.758397934778766047437; /* 0xbfe844cb, 0xbee751d9 */
 const P4: f64 = 0.145996192886612446982; /* 0x3fc2b000, 0xd4e4edd7 */
 
+// Cube root (f64)
+///
+/// Computes the cube root of the argument.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn cbrt(x: f64) -> f64 {

src/math/cbrtf.rs

@@ -22,6 +22,9 @@ use core::f32;
 const B1: u32 = 709958130; /* B1 = (127-127.0/3-0.03306235651)*2**23 */
 const B2: u32 = 642849266; /* B2 = (127-127.0/3-24/3-0.03306235651)*2**23 */
 
+/// Cube root (f32)
+///
+/// Computes the cube root of the argument.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn cbrtf(x: f32) -> f32 {

src/math/ceil.rs

@@ -2,6 +2,9 @@ use core::f64;
 
 const TOINT: f64 = 1. / f64::EPSILON;
 
+/// Ceil (f64)
+///
+/// Finds the nearest integer greater than or equal to `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn ceil(x: f64) -> f64 {

src/math/ceilf.rs

@@ -1,5 +1,8 @@
 use core::f32;
 
+/// Ceil (f32)
+///
+/// Finds the nearest integer greater than or equal to `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn ceilf(x: f32) -> f32 {

src/math/copysign.rs

@@ -1,3 +1,7 @@
+/// Sign of Y, magnitude of X (f64)
+///
+/// Constructs a number with the magnitude (absolute value) of its
+/// first argument, `x`, and the sign of its second argument, `y`.
 pub fn copysign(x: f64, y: f64) -> f64 {
     let mut ux = x.to_bits();
     let uy = y.to_bits();

src/math/copysignf.rs

@@ -1,3 +1,7 @@
+/// Sign of Y, magnitude of X (f32)
+///
+/// Constructs a number with the magnitude (absolute value) of its
+/// first argument, `x`, and the sign of its second argument, `y`.
 pub fn copysignf(x: f32, y: f32) -> f32 {
     let mut ux = x.to_bits();
     let uy = y.to_bits();

src/math/cosh.rs

@@ -2,6 +2,11 @@ use super::exp;
 use super::expm1;
 use super::k_expo2;
 
+/// Hyperbolic cosine (f64)
+///
+/// Computes the hyperbolic cosine of the argument x.
+/// Is defined as `(exp(x) + exp(-x))/2`
+/// Angles are specified in radians.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn cosh(mut x: f64) -> f64 {

src/math/coshf.rs

@@ -2,6 +2,11 @@ use super::expf;
 use super::expm1f;
 use super::k_expo2f;
 
+/// Hyperbolic cosine (f64)
+///
+/// Computes the hyperbolic cosine of the argument x.
+/// Is defined as `(exp(x) + exp(-x))/2`
+/// Angles are specified in radians.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn coshf(mut x: f32) -> f32 {

src/math/erf.rs

@@ -214,6 +214,11 @@ fn erfc2(ix: u32, mut x: f64) -> f64 {
     exp(-z * z - 0.5625) * exp((z - x) * (z + x) + r / big_s) / x
 }
 
+/// Error function (f64)
+///
+/// Calculates an approximation to the “error function”, which estimates
+/// the probability that an observation will fall within x standard
+/// deviations of the mean (assuming a normal distribution).
 pub fn erf(x: f64) -> f64 {
     let r: f64;
     let s: f64;
@@ -257,6 +262,12 @@ pub fn erf(x: f64) -> f64 {
     }
 }
 
+/// Error function (f64)
+///
+/// Calculates the complementary probability.
+/// Is `1 - erf(x)`. Is computed directly, so that you can use it to avoid
+/// the loss of precision that would result from subtracting
+/// large probabilities (on large `x`) from 1.
 pub fn erfc(x: f64) -> f64 {
     let r: f64;
     let s: f64;

src/math/erff.rs

@@ -125,6 +125,11 @@ fn erfc2(mut ix: u32, mut x: f32) -> f32 {
     expf(-z * z - 0.5625) * expf((z - x) * (z + x) + r / big_s) / x
 }
 
+/// Error function (f32)
+///
+/// Calculates an approximation to the “error function”, which estimates
+/// the probability that an observation will fall within x standard
+/// deviations of the mean (assuming a normal distribution).
 pub fn erff(x: f32) -> f32 {
     let r: f32;
     let s: f32;
@@ -168,6 +173,12 @@ pub fn erff(x: f32) -> f32 {
     }
 }
 
+/// Error function (f32)
+///
+/// Calculates the complementary probability.
+/// Is `1 - erf(x)`. Is computed directly, so that you can use it to avoid
+/// the loss of precision that would result from subtracting
+/// large probabilities (on large `x`) from 1.
 pub fn erfcf(x: f32) -> f32 {
     let r: f32;
     let s: f32;

src/math/exp.rs

@@ -77,6 +77,10 @@ const P3: f64 = 6.61375632143793436117e-05; /* 0x3F11566A, 0xAF25DE2C */
 const P4: f64 = -1.65339022054652515390e-06; /* 0xBEBBBD41, 0xC5D26BF1 */
 const P5: f64 = 4.13813679705723846039e-08; /* 0x3E663769, 0x72BEA4D0 */
 
+/// Exponential, base *e* (f64)
+///
+/// Calculate the exponential of `x`, that is, *e* raised to the power `x`
+/// (where *e* is the base of the natural system of logarithms, approximately 2.71828).
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn exp(mut x: f64) -> f64 {

src/math/exp2.rs

@@ -318,6 +318,10 @@ static TBL: [u64; TBLSIZE * 2] = [
 //
 //      Gal, S. and Bachelis, B.  An Accurate Elementary Mathematical Library
 //      for the IEEE Floating Point Standard.  TOMS 17(1), 26-46 (1991).
+
+/// Exponential, base 2 (f64)
+///
+/// Calculate `2^x`, that is, 2 raised to the power `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn exp2(mut x: f64) -> f64 {

src/math/exp2f.rs

@@ -69,6 +69,10 @@ static EXP2FT: [u64; TBLSIZE] = [
 //
 //      Tang, P.  Table-driven Implementation of the Exponential Function
 //      in IEEE Floating-Point Arithmetic.  TOMS 15(2), 144-157 (1989).
+
+/// Exponential, base 2 (f32)
+///
+/// Calculate `2^x`, that is, 2 raised to the power `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn exp2f(mut x: f32) -> f32 {

src/math/expf.rs

@@ -26,6 +26,10 @@ const INV_LN2: f32 = 1.4426950216e+00; /* 0x3fb8aa3b */
 const P1: f32 = 1.6666625440e-1; /*  0xaaaa8f.0p-26 */
 const P2: f32 = -2.7667332906e-3; /* -0xb55215.0p-32 */
 
+/// Exponential, base *e* (f32)
+///
+/// Calculate the exponential of `x`, that is, *e* raised to the power `x`
+/// (where *e* is the base of the natural system of logarithms, approximately 2.71828).
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn expf(mut x: f32) -> f32 {

src/math/expm1.rs

@@ -23,6 +23,13 @@ const Q3: f64 = -7.93650757867487942473e-05; /* BF14CE19 9EAADBB7 */
 const Q4: f64 = 4.00821782732936239552e-06; /* 3ED0CFCA 86E65239 */
 const Q5: f64 = -2.01099218183624371326e-07; /* BE8AFDB7 6E09C32D */
 
+/// Exponential, base *e*, of x-1 (f64)
+///
+/// Calculates the exponential of `x` and subtract 1, that is, *e* raised
+/// to the power `x` minus 1 (where *e* is the base of the natural
+/// system of logarithms, approximately 2.71828).
+/// The result is accurate even for small values of `x`,
+/// where using `exp(x)-1` would lose many significant digits.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn expm1(mut x: f64) -> f64 {

src/math/expm1f.rs

@@ -25,6 +25,13 @@ const INV_LN2: f32 = 1.4426950216e+00; /* 0x3fb8aa3b */
 const Q1: f32 = -3.3333212137e-2; /* -0x888868.0p-28 */
 const Q2: f32 = 1.5807170421e-3; /*  0xcf3010.0p-33 */
 
+/// Exponential, base *e*, of x-1 (f32)
+///
+/// Calculates the exponential of `x` and subtract 1, that is, *e* raised
+/// to the power `x` minus 1 (where *e* is the base of the natural
+/// system of logarithms, approximately 2.71828).
+/// The result is accurate even for small values of `x`,
+/// where using `exp(x)-1` would lose many significant digits.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn expm1f(mut x: f32) -> f32 {

src/math/fabs.rs

@@ -1,5 +1,8 @@
 use core::u64;
 
+/// Absolute value (magnitude) (f64)
+/// Calculates the absolute value (magnitude) of the argument `x`,
+/// by direct manipulation of the bit representation of `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn fabs(x: f64) -> f64 {

src/math/fabsf.rs

@@ -1,3 +1,6 @@
+/// Absolute value (magnitude) (f32)
+/// Calculates the absolute value (magnitude) of the argument `x`,
+/// by direct manipulation of the bit representation of `x`.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn fabsf(x: f32) -> f32 {

src/math/fdim.rs

@@ -1,5 +1,13 @@
 use core::f64;
 
+/// Positive difference (f64)
+///
+/// Determines the positive difference between arguments, returning:
+/// * x - y	if x > y, or
+/// * +0	if x <= y, or
+/// * NAN	if either argument is NAN.
+///
+/// A range error may occur.
 #[inline]
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn fdim(x: f64, y: f64) -> f64 {