rustdoc improvements (#78)

src/f32ext.rs

@@ -9,74 +9,74 @@ pub trait F32Ext: Sized {
     /// implementation.
     fn abs(self) -> f32;
 
-    /// Approximate `acos(x)` in radians in the range `[0, pi]`
+    /// Approximates `acos(x)` in radians in the range `[0, pi]`
     fn acos(self) -> f32;
 
-    /// Approximate `asin(x)` in radians in the range `[-pi/2, pi/2]`.
+    /// Approximates `asin(x)` in radians in the range `[-pi/2, pi/2]`.
     fn asin(self) -> f32;
 
-    /// Approximate `atan(x)` in radians with a maximum error of `0.002`.
+    /// Approximates `atan(x)` in radians with a maximum error of `0.002`.
     fn atan(self) -> f32;
 
-    /// Approximate `atan(x)` normalized to the `[−1,1]` range with a maximum
+    /// Approximates `atan(x)` normalized to the `[−1,1]` range with a maximum
     /// error of `0.1620` degrees.
     fn atan_norm(self) -> f32;
 
-    /// Approximate the four quadrant arctangent `atan2(x)` in radians, with
+    /// Approximates the four quadrant arctangent `atan2(x)` in radians, with
     /// a maximum error of `0.002`.
     fn atan2(self, other: f32) -> f32;
 
-    /// Approximate the four quadrant arctangent.
+    /// Approximates the four quadrant arctangent.
     /// Normalized to the `[0,4)` range with a maximum error of `0.1620` degrees.
     fn atan2_norm(self, other: f32) -> f32;
 
-    /// Approximate floating point ceiling.
+    /// Approximates floating point ceiling.
     fn ceil(self) -> f32;
 
     /// Copies the sign from one number to another and returns it.
     fn copysign(self, sign: f32) -> f32;
 
-    /// Approximate cosine in radians with a maximum error of `0.002`.
+    /// Approximates cosine in radians with a maximum error of `0.002`.
     fn cos(self) -> f32;
 
     /// Calculates Euclidean division, the matching method for `rem_euclid`.
     fn div_euclid(self, other: f32) -> f32;
 
-    /// Approximate `e^x`.
+    /// Approximates `e^x`.
     fn exp(self) -> f32;
 
-    /// Approximate floating point floor.
+    /// Approximates floating point floor.
     fn floor(self) -> f32;
 
     /// Retrieve the fractional part of floating point with sign.
     fn fract(self) -> f32;
 
-    /// Approximate the length of the hypotenuse of a right-angle triangle given
+    /// Approximates the length of the hypotenuse of a right-angle triangle given
     /// legs of length `x` and `y`.
     fn hypot(self, other: f32) -> f32;
 
-    /// Approximate `1/x` with an average deviation of ~8%.
+    /// Approximates `1/x` with an average deviation of ~8%.
     fn inv(self) -> f32;
 
-    /// Approximate inverse square root with an average deviation of ~5%.
+    /// Approximates inverse square root with an average deviation of ~5%.
     fn invsqrt(self) -> f32;
 
-    /// Approximate `ln(x)`.
+    /// Approximates `ln(x)`.
     fn ln(self) -> f32;
 
-    /// Approximate `log` with an arbitrary base.
+    /// Approximates `log` with an arbitrary base.
     fn log(self, base: f32) -> f32;
 
-    /// Approximate `log2`.
+    /// Approximates `log2`.
     fn log2(self) -> f32;
 
-    /// Approximate `log10`.
+    /// Approximates `log10`.
     fn log10(self) -> f32;
 
-    /// Approximate `self^n`.
+    /// Approximates `self^n`.
     fn powf(self, n: f32) -> f32;
 
-    /// Approximate `self^n` where n is an `i32`
+    /// Approximates `self^n` where n is an `i32`
     fn powi(self, n: i32) -> f32;
 
     /// Calculates the least nonnegative remainder of `self (mod other)`.
@@ -85,13 +85,13 @@ pub trait F32Ext: Sized {
     /// Round the number part of floating point with sign.
     fn round(self) -> f32;
 
-    /// Approximate sine in radians with a maximum error of `0.002`.
+    /// Approximates sine in radians with a maximum error of `0.002`.
     fn sin(self) -> f32;
 
-    /// Approximate square root with an average deviation of ~5%.
+    /// Approximates square root with an average deviation of ~5%.
     fn sqrt(self) -> f32;
 
-    /// Approximate `tan(x)` in radians with a maximum error of `0.6`.
+    /// Approximates `tan(x)` in radians with a maximum error of `0.6`.
     fn tan(self) -> f32;
 
     /// Retrieve whole number part of floating point with sign.

src/float/atan.rs

@@ -7,7 +7,8 @@ use super::F32;
 use core::f32::consts::FRAC_PI_2;
 
 impl F32 {
-    /// Computes `atan(x)` approximation in radians.
+    /// Approximates `atan(x)` approximation in radians with a maximum error of
+    /// `0.002`.
     ///
     /// Returns [`Self::NAN`] if the number is [`Self::NAN`].
     pub fn atan(self) -> Self {

src/float/atan2.rs

@@ -6,7 +6,8 @@ use super::F32;
 use core::f32::consts::PI;
 
 impl F32 {
-    /// Computes the four quadrant arctangent of `self` (`y`) and `rhs` (`x`) in radians.
+    /// Approximates the four quadrant arctangent of `self` (`y`) and
+    /// `rhs` (`x`) in radians with a maximum error of `0.002`.
     ///
     /// - `x = 0`, `y = 0`: `0`
     /// - `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`

src/float/ceil.rs

@@ -3,7 +3,8 @@
 use super::F32;
 
 impl F32 {
-    pub(crate) fn ceil(self) -> Self {
+    /// Returns the smallest integer greater than or equal to a number.
+    pub fn ceil(self) -> Self {
         -(-self).floor()
     }
 }

src/float/fract.rs

@@ -4,7 +4,7 @@ use super::F32;
 use super::{EXPONENT_BIAS, MANTISSA_BITS, MANTISSA_MASK};
 
 impl F32 {
-    /// Returns the fractional part of a number.
+    /// Returns the fractional part of a number with sign.
     pub fn fract(self) -> Self {
         let x_bits = self.to_bits();
         let exponent = self.extract_exponent_value();

src/float/ln.rs

@@ -1,4 +1,4 @@
-//! natural log (ln) approximation for a single-precision float.
+//! Natural log (ln) approximation for a single-precision float.
 //!
 //! Method described at: <https://stackoverflow.com/a/44232045/>
 //!
@@ -9,7 +9,7 @@ use super::{EXPONENT_MASK, F32};
 use core::f32::consts::LN_2;
 
 impl F32 {
-    /// Returns the natural logarithm of the number.
+    /// Approximates the natural logarithm of the number.
     // Note: excessive precision ignored because it hides the origin of the numbers used for the
     // ln(1.0->2.0) polynomial
     #[allow(clippy::excessive_precision)]

src/float/log.rs

@@ -3,7 +3,7 @@
 use super::F32;
 
 impl F32 {
-    /// Returns the logarithm of the number with respect to an arbitrary base.
+    /// Approximates the logarithm of the number with respect to an arbitrary base.
     pub fn log(self, base: Self) -> Self {
         (Self::ONE / base.ln()) * self.ln()
     }

src/float/log10.rs

@@ -4,7 +4,7 @@ use super::F32;
 use core::f32::consts::LOG10_E;
 
 impl F32 {
-    /// Returns the base 10 logarithm of the number.
+    /// Approximates the base 10 logarithm of the number.
     pub fn log10(self) -> Self {
         self.ln() * LOG10_E
     }

src/float/log2.rs

@@ -4,7 +4,7 @@ use super::F32;
 use core::f32::consts::LOG2_E;
 
 impl F32 {
-    /// Returns the base 2 logarithm of the number.
+    /// Approximates the base 2 logarithm of the number.
     pub fn log2(self) -> Self {
         self.ln() * LOG2_E
     }

src/float/powf.rs

@@ -3,7 +3,7 @@
 use super::F32;
 
 impl F32 {
-    /// Raises a number to a floating point power.
+    /// Approximates a number raised to a floating point power.
     pub fn powf(self, n: Self) -> Self {
         // using x^n = exp(ln(x^n)) = exp(n*ln(x))
         if self >= Self::ZERO {
@@ -143,7 +143,7 @@ mod tests {
         (10.0, 5.766_504e21),
     ];
 
-    ///  misc powf(x,n) test vectors - `(base_input, power_input, output)`
+    /// misc powf(x,n) test vectors - `(base_input, power_input, output)`
     pub(crate) const TEST_VECTORS_MISC: &[(f32, f32, f32)] = &[
         (-0.5881598, 2.0, 0.345_931_95),
         (-0.5881598, 3.2, f32::NAN),

src/float/powi.rs

@@ -9,7 +9,7 @@
 use super::{F32, MANTISSA_BITS};
 
 impl F32 {
-    /// Raises a number to an integer power.
+    /// Approximates a number raised to an integer power.
     pub fn powi(self, n: i32) -> Self {
         let mut base = self;
         let mut abs_n = i32::abs(n);

src/float/sqrt.rs

@@ -5,7 +5,7 @@
 use super::F32;
 
 impl F32 {
-    /// Returns the square root of a number.
+    /// Approximates the square root of a number with an average deviation of ~5%.
     ///
     /// Returns [`Self::NAN`] if `self` is a negative number.
     pub fn sqrt(self) -> Self {

src/float/tan.rs

@@ -3,7 +3,7 @@
 use super::F32;
 
 impl F32 {
-    /// Computes `tan(x)` approximation in radians.
+    /// Approximates `tan(x)` in radians with a maximum error of `0.6`.
     pub fn tan(self) -> Self {
         self.sin() / self.cos()
     }

src/lib.rs

@@ -2,16 +2,20 @@
 //! floating point approximations for common arithmetic operations, as well as
 //! 2D and 3D vector types, statistical analysis functions, and quaternions.
 //!
-//! ## Floating point approximations
+//! ## Floating point approximations: `F32` and `F32Ext`
 //!
 //! `micromath` supports approximating many arithmetic operations on `f32`
 //! using bitwise operations, providing great performance and small code size
 //! at the cost of precision. For use cases like graphics and signal
 //! processing, these approximations are often sufficient and the performance
 //! gains worth the lost precision.
 //!
-//! These approximations are provided by the [`F32Ext`] trait which is impl'd
-//! for `f32`, providing a drop-in `std`-compatible (sans lost precision) API.
+//! These approximations are defined on the [`F32`] newtype wrapper.
+//!
+//! ### `F32Ext` extension trait
+//!
+//! Floating point approximations can used via the the [`F32Ext`] trait which
+//! is impl'd for `f32`, providing a drop-in `std`-compatible API.
 //!
 //! ```
 //! use micromath::F32Ext;
@@ -20,8 +24,6 @@
 //! assert_eq!(n, 1.5); // close enough
 //! ```
 //!
-//! ### Unused import warnings when linking `std`
-//!
 //! Since the `F32Ext` trait provides methods which are already defined in
 //! `std`, in cases where your crate links `std` the `F32Ext` versions of
 //! the same methods will not be used, in which case you will get an unused