Add basic docstrings to some functions (#337)

JSorngard · web-flow · commit c3ab752b6084 · 2024-10-28T12:12:45.000-05:00
* Add docstring to Bessel functions * Add docstrings to logarithm functions * Add docstrings to pow functions * Specify argument bit-size of the Bessel functions * Specify argument bit-size for pow functions * Specify argument bit-size for logarithms * Add docstrings to sin, cos, sincos and sinh functions * Add docstrings to sqrt * Add docstrings to tan and tanh functions * Add an inline link to https://en.wikipedia.org/wiki/Bessel_function to the docstrings of all Bessel functions.
diff --git a/src/math/cos.rs b/src/math/cos.rs
@@ -41,6 +41,10 @@ use super::{k_cos, k_sin, rem_pio2};
 // Accuracy:
 //      TRIG(x) returns trig(x) nearly rounded
 //
+
+/// The cosine of `x` (f64).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn cos(x: f64) -> f64 {
     let ix = (f64::to_bits(x) >> 32) as u32 & 0x7fffffff;
diff --git a/src/math/cosf.rs b/src/math/cosf.rs
@@ -24,6 +24,9 @@ const C2_PIO2: f64 = 2. * FRAC_PI_2; /* 0x400921FB, 0x54442D18 */
 const C3_PIO2: f64 = 3. * FRAC_PI_2; /* 0x4012D97C, 0x7F3321D2 */
 const C4_PIO2: f64 = 4. * FRAC_PI_2; /* 0x401921FB, 0x54442D18 */
 
+/// The cosine of `x` (f32).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn cosf(x: f32) -> f32 {
     let x64 = x as f64;
diff --git a/src/math/j0.rs b/src/math/j0.rs
@@ -109,6 +109,7 @@ const S02: f64 = 1.16926784663337450260e-04; /* 0x3F1EA6D2, 0xDD57DBF4 */
 const S03: f64 = 5.13546550207318111446e-07; /* 0x3EA13B54, 0xCE84D5A9 */
 const S04: f64 = 1.16614003333790000205e-09; /* 0x3E1408BC, 0xF4745D8F */
 
+/// Zeroth order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f64).
 pub fn j0(mut x: f64) -> f64 {
     let z: f64;
     let r: f64;
@@ -162,6 +163,7 @@ const V02: f64 = 7.60068627350353253702e-05; /* 0x3F13ECBB, 0xF578C6C1 */
 const V03: f64 = 2.59150851840457805467e-07; /* 0x3E91642D, 0x7FF202FD */
 const V04: f64 = 4.41110311332675467403e-10; /* 0x3DFE5018, 0x3BD6D9EF */
 
+/// Zeroth order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f64).
 pub fn y0(x: f64) -> f64 {
     let z: f64;
     let u: f64;
diff --git a/src/math/j0f.rs b/src/math/j0f.rs
@@ -62,6 +62,7 @@ const S02: f32 = 1.1692678527e-04; /* 0x38f53697 */
 const S03: f32 = 5.1354652442e-07; /* 0x3509daa6 */
 const S04: f32 = 1.1661400734e-09; /* 0x30a045e8 */
 
+/// Zeroth order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f32).
 pub fn j0f(mut x: f32) -> f32 {
     let z: f32;
     let r: f32;
@@ -107,6 +108,7 @@ const V02: f32 = 7.6006865129e-05; /* 0x389f65e0 */
 const V03: f32 = 2.5915085189e-07; /* 0x348b216c */
 const V04: f32 = 4.4111031494e-10; /* 0x2ff280c2 */
 
+/// Zeroth order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f32).
 pub fn y0f(x: f32) -> f32 {
     let z: f32;
     let u: f32;
diff --git a/src/math/j1.rs b/src/math/j1.rs
@@ -113,6 +113,7 @@ const S03: f64 = 1.17718464042623683263e-06; /* 0x3EB3BFF8, 0x333F8498 */
 const S04: f64 = 5.04636257076217042715e-09; /* 0x3E35AC88, 0xC97DFF2C */
 const S05: f64 = 1.23542274426137913908e-11; /* 0x3DAB2ACF, 0xCFB97ED8 */
 
+/// First order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f64).
 pub fn j1(x: f64) -> f64 {
     let mut z: f64;
     let r: f64;
@@ -158,6 +159,7 @@ const V0: [f64; 5] = [
     1.66559246207992079114e-11, /* 0x3DB25039, 0xDACA772A */
 ];
 
+/// First order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f64).
 pub fn y1(x: f64) -> f64 {
     let z: f64;
     let u: f64;
diff --git a/src/math/j1f.rs b/src/math/j1f.rs
@@ -63,6 +63,7 @@ const S03: f32 = 1.1771846857e-06; /* 0x359dffc2 */
 const S04: f32 = 5.0463624390e-09; /* 0x31ad6446 */
 const S05: f32 = 1.2354227016e-11; /* 0x2d59567e */
 
+/// First order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f32).
 pub fn j1f(x: f32) -> f32 {
     let mut z: f32;
     let r: f32;
@@ -107,6 +108,7 @@ const V0: [f32; 5] = [
     1.6655924903e-11, /* 0x2d9281cf */
 ];
 
+/// First order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f32).
 pub fn y1f(x: f32) -> f32 {
     let z: f32;
     let u: f32;
diff --git a/src/math/jn.rs b/src/math/jn.rs
@@ -38,6 +38,7 @@ use super::{cos, fabs, get_high_word, get_low_word, j0, j1, log, sin, sqrt, y0,
 
 const INVSQRTPI: f64 = 5.64189583547756279280e-01; /* 0x3FE20DD7, 0x50429B6D */
 
+/// Integer order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f64).
 pub fn jn(n: i32, mut x: f64) -> f64 {
     let mut ix: u32;
     let lx: u32;
@@ -247,6 +248,7 @@ pub fn jn(n: i32, mut x: f64) -> f64 {
     if sign { -b } else { b }
 }
 
+/// Integer order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f64).
 pub fn yn(n: i32, x: f64) -> f64 {
     let mut ix: u32;
     let lx: u32;
diff --git a/src/math/jnf.rs b/src/math/jnf.rs
@@ -15,6 +15,7 @@
 
 use super::{fabsf, j0f, j1f, logf, y0f, y1f};
 
+/// Integer order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the first kind (f32).
 pub fn jnf(n: i32, mut x: f32) -> f32 {
     let mut ix: u32;
     let mut nm1: i32;
@@ -191,6 +192,7 @@ pub fn jnf(n: i32, mut x: f32) -> f32 {
     if sign { -b } else { b }
 }
 
+/// Integer order of the [Bessel function](https://en.wikipedia.org/wiki/Bessel_function) of the second kind (f32).
 pub fn ynf(n: i32, x: f32) -> f32 {
     let mut ix: u32;
     let mut ib: u32;
diff --git a/src/math/log.rs b/src/math/log.rs
@@ -70,6 +70,7 @@ const LG5: f64 = 1.818357216161805012e-01; /* 3FC74664 96CB03DE */
 const LG6: f64 = 1.531383769920937332e-01; /* 3FC39A09 D078C69F */
 const LG7: f64 = 1.479819860511658591e-01; /* 3FC2F112 DF3E5244 */
 
+/// The natural logarithm of `x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log(mut x: f64) -> f64 {
     let x1p54 = f64::from_bits(0x4350000000000000); // 0x1p54 === 2 ^ 54
diff --git a/src/math/log10.rs b/src/math/log10.rs
@@ -31,6 +31,7 @@ const LG5: f64 = 1.818357216161805012e-01; /* 3FC74664 96CB03DE */
 const LG6: f64 = 1.531383769920937332e-01; /* 3FC39A09 D078C69F */
 const LG7: f64 = 1.479819860511658591e-01; /* 3FC2F112 DF3E5244 */
 
+/// The base 10 logarithm of `x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log10(mut x: f64) -> f64 {
     let x1p54 = f64::from_bits(0x4350000000000000); // 0x1p54 === 2 ^ 54
diff --git a/src/math/log10f.rs b/src/math/log10f.rs
@@ -25,6 +25,7 @@ const LG2: f32 = 0.40000972152; /* 0xccce13.0p-25 */
 const LG3: f32 = 0.28498786688; /* 0x91e9ee.0p-25 */
 const LG4: f32 = 0.24279078841; /* 0xf89e26.0p-26 */
 
+/// The base 10 logarithm of `x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log10f(mut x: f32) -> f32 {
     let x1p25f = f32::from_bits(0x4c000000); // 0x1p25f === 2 ^ 25
diff --git a/src/math/log1p.rs b/src/math/log1p.rs
@@ -65,6 +65,7 @@ const LG5: f64 = 1.818357216161805012e-01; /* 3FC74664 96CB03DE */
 const LG6: f64 = 1.531383769920937332e-01; /* 3FC39A09 D078C69F */
 const LG7: f64 = 1.479819860511658591e-01; /* 3FC2F112 DF3E5244 */
 
+/// The natural logarithm of 1+`x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log1p(x: f64) -> f64 {
     let mut ui: u64 = x.to_bits();
diff --git a/src/math/log1pf.rs b/src/math/log1pf.rs
@@ -20,6 +20,7 @@ const LG2: f32 = 0.40000972152; /* 0xccce13.0p-25 */
 const LG3: f32 = 0.28498786688; /* 0x91e9ee.0p-25 */
 const LG4: f32 = 0.24279078841; /* 0xf89e26.0p-26 */
 
+/// The natural logarithm of 1+`x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log1pf(x: f32) -> f32 {
     let mut ui: u32 = x.to_bits();
diff --git a/src/math/log2.rs b/src/math/log2.rs
@@ -29,6 +29,7 @@ const LG5: f64 = 1.818357216161805012e-01; /* 3FC74664 96CB03DE */
 const LG6: f64 = 1.531383769920937332e-01; /* 3FC39A09 D078C69F */
 const LG7: f64 = 1.479819860511658591e-01; /* 3FC2F112 DF3E5244 */
 
+/// The base 2 logarithm of `x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log2(mut x: f64) -> f64 {
     let x1p54 = f64::from_bits(0x4350000000000000); // 0x1p54 === 2 ^ 54
diff --git a/src/math/log2f.rs b/src/math/log2f.rs
@@ -23,6 +23,7 @@ const LG2: f32 = 0.40000972152; /* 0xccce13.0p-25 */
 const LG3: f32 = 0.28498786688; /* 0x91e9ee.0p-25 */
 const LG4: f32 = 0.24279078841; /* 0xf89e26.0p-26 */
 
+/// The base 2 logarithm of `x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn log2f(mut x: f32) -> f32 {
     let x1p25f = f32::from_bits(0x4c000000); // 0x1p25f === 2 ^ 25
diff --git a/src/math/logf.rs b/src/math/logf.rs
@@ -21,6 +21,7 @@ const LG2: f32 = 0.40000972152; /*  0xccce13.0p-25 */
 const LG3: f32 = 0.28498786688; /*  0x91e9ee.0p-25 */
 const LG4: f32 = 0.24279078841; /*  0xf89e26.0p-26 */
 
+/// The natural logarithm of `x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn logf(mut x: f32) -> f32 {
     let x1p25 = f32::from_bits(0x4c000000); // 0x1p25f === 2 ^ 25
diff --git a/src/math/pow.rs b/src/math/pow.rs
@@ -89,6 +89,7 @@ const IVLN2: f64 = 1.44269504088896338700e+00; /* 0x3ff71547_652b82fe =1/ln2 */
 const IVLN2_H: f64 = 1.44269502162933349609e+00; /* 0x3ff71547_60000000 =24b 1/ln2*/
 const IVLN2_L: f64 = 1.92596299112661746887e-08; /* 0x3e54ae0b_f85ddf44 =1/ln2 tail*/
 
+/// Returns `x` to the power of `y` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn pow(x: f64, y: f64) -> f64 {
     let t1: f64;
diff --git a/src/math/powf.rs b/src/math/powf.rs
@@ -43,6 +43,7 @@ const IVLN2: f32 = 1.4426950216e+00;
 const IVLN2_H: f32 = 1.4426879883e+00;
 const IVLN2_L: f32 = 7.0526075433e-06;
 
+/// Returns `x` to the power of `y` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn powf(x: f32, y: f32) -> f32 {
     let mut z: f32;
diff --git a/src/math/sin.rs b/src/math/sin.rs
@@ -40,6 +40,10 @@ use super::{k_cos, k_sin, rem_pio2};
 //
 // Accuracy:
 //      TRIG(x) returns trig(x) nearly rounded
+
+/// The sine of `x` (f64).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sin(x: f64) -> f64 {
     let x1p120 = f64::from_bits(0x4770000000000000); // 0x1p120f === 2 ^ 120
diff --git a/src/math/sincos.rs b/src/math/sincos.rs
@@ -12,6 +12,9 @@
 
 use super::{get_high_word, k_cos, k_sin, rem_pio2};
 
+/// Both the sine and cosine of `x` (f64).
+///
+/// `x` is specified in radians and the return value is (sin(x), cos(x)).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sincos(x: f64) -> (f64, f64) {
     let s: f64;
diff --git a/src/math/sincosf.rs b/src/math/sincosf.rs
@@ -23,6 +23,9 @@ const S2PIO2: f32 = 2.0 * PI_2; /* 0x400921FB, 0x54442D18 */
 const S3PIO2: f32 = 3.0 * PI_2; /* 0x4012D97C, 0x7F3321D2 */
 const S4PIO2: f32 = 4.0 * PI_2; /* 0x401921FB, 0x54442D18 */
 
+/// Both the sine and cosine of `x` (f32).
+///
+/// `x` is specified in radians and the return value is (sin(x), cos(x)).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sincosf(x: f32) -> (f32, f32) {
     let s: f32;
diff --git a/src/math/sinf.rs b/src/math/sinf.rs
@@ -24,6 +24,9 @@ const S2_PIO2: f64 = 2. * FRAC_PI_2; /* 0x400921FB, 0x54442D18 */
 const S3_PIO2: f64 = 3. * FRAC_PI_2; /* 0x4012D97C, 0x7F3321D2 */
 const S4_PIO2: f64 = 4. * FRAC_PI_2; /* 0x401921FB, 0x54442D18 */
 
+/// The sine of `x` (f32).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sinf(x: f32) -> f32 {
     let x64 = x as f64;
diff --git a/src/math/sinh.rs b/src/math/sinh.rs
@@ -4,6 +4,8 @@ use super::{expm1, expo2};
 //         = (exp(x)-1 + (exp(x)-1)/exp(x))/2
 //         = x + x^3/6 + o(x^5)
 //
+
+/// The hyperbolic sine of `x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sinh(x: f64) -> f64 {
     // union {double f; uint64_t i;} u = {.f = x};
diff --git a/src/math/sinhf.rs b/src/math/sinhf.rs
@@ -1,5 +1,6 @@
 use super::{expm1f, k_expo2f};
 
+/// The hyperbolic sine of `x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sinhf(x: f32) -> f32 {
     let mut h = 0.5f32;
diff --git a/src/math/sqrt.rs b/src/math/sqrt.rs
@@ -78,6 +78,7 @@
 
 use core::f64;
 
+/// The square root of `x` (f64).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sqrt(x: f64) -> f64 {
     // On wasm32 we know that LLVM's intrinsic will compile to an optimized
diff --git a/src/math/sqrtf.rs b/src/math/sqrtf.rs
@@ -13,6 +13,7 @@
  * ====================================================
  */
 
+/// The square root of `x` (f32).
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn sqrtf(x: f32) -> f32 {
     // On wasm32 we know that LLVM's intrinsic will compile to an optimized
diff --git a/src/math/tan.rs b/src/math/tan.rs
@@ -39,6 +39,10 @@ use super::{k_tan, rem_pio2};
 //
 // Accuracy:
 //      TRIG(x) returns trig(x) nearly rounded
+
+/// The tangent of `x` (f64).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn tan(x: f64) -> f64 {
     let x1p120 = f32::from_bits(0x7b800000); // 0x1p120f === 2 ^ 120
diff --git a/src/math/tanf.rs b/src/math/tanf.rs
@@ -24,6 +24,9 @@ const T2_PIO2: f64 = 2. * FRAC_PI_2; /* 0x400921FB, 0x54442D18 */
 const T3_PIO2: f64 = 3. * FRAC_PI_2; /* 0x4012D97C, 0x7F3321D2 */
 const T4_PIO2: f64 = 4. * FRAC_PI_2; /* 0x401921FB, 0x54442D18 */
 
+/// The tangent of `x` (f32).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn tanf(x: f32) -> f32 {
     let x64 = x as f64;
diff --git a/src/math/tanh.rs b/src/math/tanh.rs
@@ -4,6 +4,10 @@ use super::expm1;
  *         = (exp(2*x) - 1)/(exp(2*x) - 1 + 2)
  *         = (1 - exp(-2*x))/(exp(-2*x) - 1 + 2)
  */
+
+/// The hyperbolic tangent of `x` (f64).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn tanh(mut x: f64) -> f64 {
     let mut uf: f64 = x;
diff --git a/src/math/tanhf.rs b/src/math/tanhf.rs
@@ -1,5 +1,8 @@
 use super::expm1f;
 
+/// The hyperbolic tangent of `x` (f32).
+///
+/// `x` is specified in radians.
 #[cfg_attr(all(test, assert_no_panic), no_panic::no_panic)]
 pub fn tanhf(mut x: f32) -> f32 {
     /* x = |x| */
