Add documentation

Author: calebzulawski

crates/core_simd/tests/helpers/biteq.rs

@@ -1,7 +1,3 @@
-#[macro_use]
-#[path = "../helpers/mod.rs"]
-mod helpers;
-
 #[macro_use]
 mod mask_macros;
 

crates/core_simd/tests/helpers/mod.rs

@@ -1,3 +1,6 @@
+/// Implements a test on a unary operation using proptest.
+///
+/// Compares the vector operation to the equivalent scalar operation.
 #[macro_export]
 macro_rules! impl_unary_op_test {
     { $vector:ty, $scalar:ty, $trait:ident :: $fn:ident, $scalar_fn:expr } => {
@@ -16,6 +19,9 @@ macro_rules! impl_unary_op_test {
     };
 }
 
+/// Implements a test on a binary operation using proptest.
+///
+/// Compares the vector operation to the equivalent scalar operation.
 #[macro_export]
 macro_rules! impl_binary_op_test {
     { $vector:ty, $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident, $scalar_fn:expr } => {
@@ -70,6 +76,12 @@ macro_rules! impl_binary_op_test {
     };
 }
 
+/// Implements a test on a binary operation using proptest.
+///
+/// Like `impl_binary_op_test`, but allows providing a function for rejecting particular inputs
+/// (like the `proptest_assume` macro).
+///
+/// Compares the vector operation to the equivalent scalar operation.
 #[macro_export]
 macro_rules! impl_binary_checked_op_test {
     { $vector:ty, $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident, $scalar_fn:expr, $check_fn:expr } => {
@@ -124,6 +136,7 @@ macro_rules! impl_binary_checked_op_test {
     };
 }
 
+/// Implement tests for signed integers.
 #[macro_export]
 macro_rules! impl_signed_tests {
     { $vector:ident, $scalar:tt } => {
@@ -191,6 +204,8 @@ macro_rules! impl_signed_tests {
             impl_binary_op_test!(Vector<LANES>, Scalar, Add::add, AddAssign::add_assign, Scalar::wrapping_add);
             impl_binary_op_test!(Vector<LANES>, Scalar, Sub::sub, SubAssign::sub_assign, Scalar::wrapping_sub);
             impl_binary_op_test!(Vector<LANES>, Scalar, Mul::mul, MulAssign::mul_assign, Scalar::wrapping_mul);
+
+            // Exclude Div and Rem panicking cases
             impl_binary_checked_op_test!(Vector<LANES>, Scalar, Div::div, DivAssign::div_assign, Scalar::wrapping_div, |x, y| y != 0 && !(x == Scalar::MIN && y == -1));
             impl_binary_checked_op_test!(Vector<LANES>, Scalar, Rem::rem, RemAssign::rem_assign, Scalar::wrapping_rem, |x, y| y != 0 && !(x == Scalar::MIN && y == -1));
 
@@ -202,6 +217,7 @@ macro_rules! impl_signed_tests {
     }
 }
 
+/// Implement tests for unsigned integers.
 #[macro_export]
 macro_rules! impl_unsigned_tests {
     { $vector:ident, $scalar:tt } => {
@@ -220,6 +236,8 @@ macro_rules! impl_unsigned_tests {
             impl_binary_op_test!(Vector<LANES>, Scalar, Add::add, AddAssign::add_assign, Scalar::wrapping_add);
             impl_binary_op_test!(Vector<LANES>, Scalar, Sub::sub, SubAssign::sub_assign, Scalar::wrapping_sub);
             impl_binary_op_test!(Vector<LANES>, Scalar, Mul::mul, MulAssign::mul_assign, Scalar::wrapping_mul);
+
+            // Exclude Div and Rem panicking cases
             impl_binary_checked_op_test!(Vector<LANES>, Scalar, Div::div, DivAssign::div_assign, Scalar::wrapping_div, |_, y| y != 0);
             impl_binary_checked_op_test!(Vector<LANES>, Scalar, Rem::rem, RemAssign::rem_assign, Scalar::wrapping_rem, |_, y| y != 0);
 
@@ -231,6 +249,7 @@ macro_rules! impl_unsigned_tests {
     }
 }
 
+/// Implement tests for floating point numbers.
 #[macro_export]
 macro_rules! impl_float_tests {
     { $vector:ident, $scalar:tt, $int_scalar:tt } => {

crates/core_simd/tests/mask_ops_impl/mod.rs

@@ -1,3 +1,5 @@
+//! Generic-length array strategy.
+
 // Adapted from proptest's array code
 // Copyright 2017 Jason Lingle
 

crates/core_simd/tests/ops_macros.rs

@@ -1,3 +1,5 @@
+//! Compare numeric types by exact bit value.
+
 pub trait BitEq {
     fn biteq(&self, other: &Self) -> bool;
     fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result;

crates/test_helpers/src/array.rs

@@ -6,6 +6,9 @@ pub mod wasm;
 #[macro_use]
 pub mod biteq;
 
+/// Specifies the default strategy for testing a type.
+///
+/// This strategy should be what "makes sense" to test.
 pub trait DefaultStrategy {
     type Strategy: proptest::strategy::Strategy<Value = Self>;
     fn default_strategy() -> Self::Strategy;
@@ -74,13 +77,15 @@ impl<T: core::fmt::Debug + DefaultStrategy, const LANES: usize> DefaultStrategy
     }
 }
 
+/// Test a function that takes a single value.
 pub fn test_1<A: core::fmt::Debug + DefaultStrategy>(
     f: &dyn Fn(A) -> proptest::test_runner::TestCaseResult,
 ) {
     let mut runner = proptest::test_runner::TestRunner::default();
     runner.run(&A::default_strategy(), f).unwrap();
 }
 
+/// Test a function that takes two values.
 pub fn test_2<A: core::fmt::Debug + DefaultStrategy, B: core::fmt::Debug + DefaultStrategy>(
     f: &dyn Fn(A, B) -> proptest::test_runner::TestCaseResult,
 ) {
@@ -92,6 +97,7 @@ pub fn test_2<A: core::fmt::Debug + DefaultStrategy, B: core::fmt::Debug + Defau
         .unwrap();
 }
 
+/// Test a unary vector function against a unary scalar function, applied elementwise.
 #[inline(never)]
 pub fn test_unary_elementwise<Scalar, ScalarResult, Vector, VectorResult, const LANES: usize>(
     fv: &dyn Fn(Vector) -> VectorResult,
@@ -118,6 +124,7 @@ pub fn test_unary_elementwise<Scalar, ScalarResult, Vector, VectorResult, const
     });
 }
 
+/// Test a binary vector function against a binary scalar function, applied elementwise.
 #[inline(never)]
 pub fn test_binary_elementwise<
     Scalar1,
@@ -154,6 +161,7 @@ pub fn test_binary_elementwise<
     });
 }
 
+/// Test a binary vector-scalar function against a binary scalar function, applied elementwise.
 #[inline(never)]
 pub fn test_binary_scalar_rhs_elementwise<
     Scalar1,
@@ -188,6 +196,7 @@ pub fn test_binary_scalar_rhs_elementwise<
     });
 }
 
+/// Test a binary vector-scalar function against a binary scalar function, applied elementwise.
 #[inline(never)]
 pub fn test_binary_scalar_lhs_elementwise<
     Scalar1,
@@ -222,6 +231,7 @@ pub fn test_binary_scalar_lhs_elementwise<
     });
 }
 
+/// Expand a const-generic test into separate tests for each possible lane count.
 #[macro_export]
 macro_rules! test_lanes {
     {
@@ -282,6 +292,7 @@ macro_rules! test_lanes {
     }
 }  
 
+/// Expand a const-generic `#[should_panic]` test into separate tests for each possible lane count.
 #[macro_export]
 macro_rules! test_lanes_panic {
     {

crates/test_helpers/src/biteq.rs

@@ -1,3 +1,5 @@
+//! Strategies for `u128` and `i128`, since proptest doesn't provide them for the wasm target.
+
 macro_rules! impl_num {
     { $name:ident } => {
         pub(crate) mod $name {