feat: support outer doc comments for naming matrix tests

Adds support for using outer doc comments (`///`) instead of
auto-generated tests names for parameterized matrix tests.

e.g.

```rust
[values(
    /// All present
    InputDirConfig {
        build_info: true,
        data_files: true,
        mtree: true,
        package_info: true,
        scriptlet: true,
    },
    /// No data files
    InputDirConfig {
        build_info: true,
        data_files: false,
        mtree: true,
        package_info: true,
        scriptlet: true,
    },
}
```

The generated tests will look like this:

```
values_1_All_present
values_2_No_data_files
```

This implementation also changes the internal `sanitize_ident` function to
allow sanitizing whitespaces as `_`.

Fixes <#320>

Signed-off-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>

Author: orhun

rstest_macros/src/parse/vlist.rs

@@ -2,12 +2,10 @@ use proc_macro2::TokenStream;
 use quote::ToTokens;
 use syn::{
     parse::{Parse, ParseStream, Result},
-    Expr, Ident, Pat, Token,
+    Attribute, Expr, ExprLit, Ident, Lit, Meta, MetaNameValue, Pat, Token,
 };
 
-use crate::refident::IntoPat;
-
-use super::expressions::Expressions;
+use crate::{refident::IntoPat, utils::sanitize_ident};
 
 #[derive(Debug, PartialEq, Clone)]
 pub(crate) struct Value {
@@ -39,25 +37,51 @@ pub(crate) struct ValueList {
     pub(crate) values: Vec<Value>,
 }
 
+/// Extracts the documentation comment from the attributes.
+fn extract_doc_comment(attrs: &[Attribute]) -> Option<String> {
+    attrs.iter().find_map(|attr| match &attr.meta {
+        Meta::NameValue(MetaNameValue {
+            path,
+            value: Expr::Lit(ExprLit {
+                lit: Lit::Str(doc), ..
+            }),
+            ..
+        }) if path.is_ident("doc") => Some(sanitize_ident(&doc.value().trim(), false)),
+        _ => None,
+    })
+}
+
 impl Parse for ValueList {
     fn parse(input: ParseStream) -> Result<Self> {
         let ident: Ident = input.parse()?;
         let _to: Token![=>] = input.parse()?;
         let content;
         let paren = syn::bracketed!(content in input);
-        let values: Expressions = content.parse()?;
 
-        let ret = Self {
-            arg: ident.into_pat(),
-            values: values.take().into_iter().map(|e| e.into()).collect(),
-        };
-        if ret.values.is_empty() {
+        let mut values = Vec::new();
+        while !content.is_empty() {
+            // Set the description from doc comments if possible
+            let attrs: Vec<Attribute> = content.call(Attribute::parse_outer)?;
+            let description = extract_doc_comment(&attrs);
+
+            // Parse the expression inside the brackets
+            let expr: Expr = content.parse()?;
+            values.push(Value::new(expr, description));
+
+            // Consume the trailing comma
+            let _ = content.parse::<Token![,]>();
+        }
+
+        if values.is_empty() {
             Err(syn::Error::new(
                 paren.span.join(),
                 "Values list should not be empty",
             ))
         } else {
-            Ok(ret)
+            Ok(Self {
+                arg: ident.into_pat(),
+                values,
+            })
         }
     }
 }
@@ -119,5 +143,29 @@ mod should {
         fn forget_brackets() {
             parse_values_list(r#"other => 42"#);
         }
+
+        #[test]
+        fn doc_comment_overrides_description() {
+            let vl = parse_values_list(
+                r#"
+                number => [
+                    /// forty two
+                    42,
+                    /// one hundred
+                    100,
+                    /// Sanitized 999 Value 😁
+                    999
+                    2,
+                ]
+            "#,
+            );
+
+            assert_eq!("number", &vl.arg.display_code());
+            assert_eq!("forty_two", vl.values[0].description());
+            assert_eq!("one_hundred", vl.values[1].description());
+            assert_eq!("Sanitized_999_Value_", vl.values[2].description());
+            // fallback to the expression name
+            assert_eq!("2", vl.values[3].description());
+        }
     }
 }

rstest_macros/src/render/mod.rs

@@ -109,7 +109,7 @@ impl ValueList {
     ) -> impl Iterator<Item = (String, ArgumentDataResolver<'a>)> + 'a {
         let max_len = self.values.len();
         self.values.iter().enumerate().map(move |(index, value)| {
-            let description = sanitize_ident(&value.description());
+            let description = sanitize_ident(&value.description(), true);
             let arg = info.arguments.inner_pat(&self.arg);
 
             let arg_name = arg

rstest_macros/src/utils.rs

@@ -281,13 +281,19 @@ pub(crate) fn fn_arg_mutability(arg: &FnArg) -> Option<syn::token::Mut> {
     }
 }
 
-pub(crate) fn sanitize_ident(name: &str) -> String {
+pub(crate) fn sanitize_ident(name: &str, filter_whitespace: bool) -> String {
     name.chars()
-        .filter(|c| !c.is_whitespace())
+        .filter(|c| {
+            if filter_whitespace {
+                !c.is_whitespace()
+            } else {
+                true
+            }
+        })
         .map(|c| match c {
             '"' | '\'' => "__".to_owned(),
             ':' | '(' | ')' | '{' | '}' | '[' | ']' | ',' | '.' | '*' | '+' | '/' | '-' | '%'
-            | '^' | '!' | '&' | '|' => "_".to_owned(),
+            | '^' | '!' | '&' | '|' | ' ' => "_".to_owned(),
             _ => c.to_string(),
         })
         .collect::<String>()
@@ -403,22 +409,33 @@ mod test {
     }
 
     #[rstest]
-    #[case("1", "1")]
-    #[case(r#""1""#, "__1__")]
-    #[case(r#"Some::SomeElse"#, "Some__SomeElse")]
-    #[case(r#""minnie".to_owned()"#, "__minnie___to_owned__")]
+    #[case("1", "1", true)]
+    #[case(r#""1""#, "__1__", true)]
+    #[case(r#"Some::SomeElse"#, "Some__SomeElse", true)]
+    #[case(r#""minnie".to_owned()"#, "__minnie___to_owned__", true)]
     #[case(
         r#"vec![1 ,   2, 
     3]"#,
-        "vec__1_2_3_"
+        "vec__1_2_3_",
+        true
     )]
     #[case(
         r#"some_macro!("first", {second}, [third])"#,
-        "some_macro____first____second___third__"
+        "some_macro____first____second___third__",
+        true
     )]
-    #[case(r#"'x'"#, "__x__")]
-    #[case::ops(r#"a*b+c/d-e%f^g"#, "a_b_c_d_e_f_g")]
-    fn sanitaze_ident_name(#[case] expression: impl AsRef<str>, #[case] expected: impl AsRef<str>) {
-        assert_eq!(expected.as_ref(), sanitize_ident(expression.as_ref()));
+    #[case(r#"'x'"#, "__x__", true)]
+    #[case::ops(r#"a*b+c/d-e%f^g"#, "a_b_c_d_e_f_g", true)]
+    #[case(r#"filter whitespace"#, "filterwhitespace", true)]
+    #[case(r#"do not filter whitespace"#, "do_not_filter_whitespace", false)]
+    fn sanitaze_ident_name(
+        #[case] expression: impl AsRef<str>,
+        #[case] expected: impl AsRef<str>,
+        #[case] filter_whitespace: bool,
+    ) {
+        assert_eq!(
+            expected.as_ref(),
+            sanitize_ident(expression.as_ref(), filter_whitespace)
+        );
     }
 }