Add basic documentation for test_matrix macro

Add unreleased CHANGELOG fragment, README documentation,
and doc comment to src/lib.rs and crate/test-case-macros/src/lib.rs.

Detailed Wiki documentation forthcoming.

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [Unreleased]
+### New features
+* Add `test_matrix` macro: generates test cases from Cartesian product of possible test function argument values.
+
 ## 3.1.0
 ### New features
 * Copy attribute span to generated test functions so that IDEs recognize them properly as individual tests

README.md

@@ -57,6 +57,39 @@ test tests::multiplication_tests::when_operands_are_swapped ... ok
 test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 ```
 
+### Test Matrix
+
+The `#[test_matrix(...)]` macro allows generating multiple test cases from the
+Cartesian product of one or more possible values for each test function argument. The
+number of arguments to the `test_matrix` macro must be the same as the number of arguments to
+the test function. Each macro argument can be:
+
+1. A list in array (`[x, y, ...]`) or tuple (`(x, y, ...)`) syntax. The values can be any
+   valid [expression](https://doc.rust-lang.org/reference/expressions.html).
+2. A closed numeric range expression (e.g. `0..100` or `1..=99`), which will generate
+   argument values for all integers in the range.
+3. A single expression, which can be used to keep one argument constant while varying the
+   other test function arguments using a list or range.
+
+#### Example usage:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use test_case::test_matrix;
+
+    #[test_matrix(
+        [-2, 2],
+        [-4, 4]
+    )]
+    fn multiplication_tests(x: i8, y: i8) {
+        let actual = (x * y).abs();
+
+        assert_eq!(8, actual)
+    }
+}
+```
+
 ## MSRV Policy
 
 Starting with version 3.0 and up `test-case` introduces policy of only supporting latest stable Rust.

crates/test-case-macros/src/lib.rs

@@ -37,6 +37,19 @@ pub fn test_case(args: TokenStream, input: TokenStream) -> TokenStream {
     render_test_cases(&test_cases, item)
 }
 
+/// Generates tests for the cartesian product of a given set of data
+///
+/// A test matrix consists of three elements:
+///
+/// 1. _(Required)_ Sets of values to combine; the nubmer of sets must be the same as the number of
+///    arguments to the test body function
+/// 2. _(Optional)_ Expected result (for all combinations of values)
+/// 3. _(Required)_ Test body
+///
+/// _Expected result_ and _Test body_ are the same as they are for the singular `#[test_case(...)]`
+/// macro but are applied to every case generated by `#[test_matrix(...)]`. `Test case description`
+/// is not allowed for `test_matrix`, because test case names are auto-generated from the test body
+/// function name and matrix values.
 #[proc_macro_attribute]
 #[proc_macro_error::proc_macro_error]
 pub fn test_matrix(args: TokenStream, input: TokenStream) -> TokenStream {

src/lib.rs

@@ -48,6 +48,39 @@
 //! test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 //! ```
 //!
+//! ## Test Matrix
+//!
+//! The `#[test_matrix(...)]` macro allows generating multiple test cases from the
+//! Cartesian product of one or more possible values for each test function argument. The
+//! number of arguments to the `test_matrix` macro must be the same as the number of arguments to
+//! the test function. Each macro argument can be:
+//!
+//!     1. A list in array (`[x, y, ...]`) or tuple (`(x, y, ...)`) syntax. The values can be any
+//!        valid [expression](https://doc.rust-lang.org/reference/expressions.html).
+//!     2. A closed numeric range expression (e.g. `0..100` or `1..=99`), which will generate
+//!        argument values for all integers in the range.
+//!     3. A single expression, which can be used to keep one argument constant while varying the
+//!        other test function arguments using a list or range.
+//!
+//! ### Example usage:
+//!
+//! ```rust
+//! #[cfg(test)]
+//! mod tests {
+//!     use test_case::test_matrix;
+//!
+//!     #[test_matrix(
+//!         [-2, 2],
+//!         [-4, 4]
+//!     )]
+//!     fn multiplication_tests(x: i8, y: i8) {
+//!         let actual = (x * y).abs();
+//!
+//!         assert_eq!(8, actual)
+//!     }
+//! }
+//! ```
+//!
 //! # MSRV Policy
 //!
 //! Starting with version 3.0 and up `test-case` introduces policy of only supporting latest stable Rust.