Introduce a #[hidden] attribute to hide the generated macro from docs (#333)

* .

* Add hidden attribute to hide public macros from docs

* Update rstest_reuse/src/lib.rs

Co-authored-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>

* Add docs and CR notes

* Add docs and tests

---------

Co-authored-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>

Author: AdamGS

rstest_reuse/README.md

@@ -180,6 +180,12 @@ pub use rstest_reuse;
 
 And not just `use rstest_reuse` like in the standard cases.
 
+## `#[hidden]` Attribute
+
+Adds a `#[doc(hidden)]` attribute to the generated macro, hiding it from documentation.
+
+When using `#[export]`, the exported macro would otherwise appear in your public docs with a random suffix (used to prevent name collisions). Using `#[hidden]` keeps your documentation clean, which is especially useful with tools like `cargo-semver-checks`.
+
 ## Disclaimer
 
 This crate is in a development stage. I don't know if I'll include it in `rstest` or change some syntax in the future.

rstest_reuse/src/lib.rs

@@ -286,6 +286,12 @@ fn get_export(attributes: &[Attribute]) -> Option<&Attribute> {
         .find(|&attr| attr.path().is_ident(&format_ident!("export")))
 }
 
+fn get_hidden(attributes: &[Attribute]) -> Option<&Attribute> {
+    attributes
+        .iter()
+        .find(|&attr| attr.path().is_ident(&format_ident!("hidden")))
+}
+
 /// Define a template where the name is given from the function name. This attribute register all
 /// attributes. The function signature don't really mater but to make it clear is better that you
 /// use a signature like if you're wrinting a standard `rstest`.
@@ -294,6 +300,9 @@ fn get_export(attributes: &[Attribute]) -> Option<&Attribute> {
 /// should annotate it with `#[export]` attribute. This attribute add `#[macro_export]` attribute to
 /// the template macro and make possible to use it from another crate.
 ///
+/// If you care about maintaining clean external docs, or use tools like `cargo-semver-check`, you
+/// can use the `#[hidden]` attribute to hide the generated macro from external rust docs.
+///
 /// When define a template you can also set the arguments attributes like `#[case]`, `#[values]`
 /// and `#[with]`: when you apply it attributes will be copied to the matched by name arguments.
 ///
@@ -333,8 +342,19 @@ pub fn template(_args: proc_macro::TokenStream, input: proc_macro::TokenStream)
     let macro_name = template.sig.ident.clone();
     let macro_name_rand = format_ident!("{}_{}", macro_name, rand::random::<u64>());
 
+    let doc = if get_hidden(&attributes).is_some() {
+        quote! {
+            #[doc(hidden)]
+        }
+    } else {
+        let docstr = format!("Apply {macro_name} template to given body");
+        quote! {
+            #[doc = #docstr]
+        }
+    };
+
     let tokens = quote! {
-        /// Apply #macro_name template to given body
+        #doc
         #macro_attribute
         macro_rules! #macro_name_rand {
             ( $test:item ) => {

rstest_reuse/tests/acceptance.rs

@@ -190,6 +190,29 @@ fn rstest_reuse_not_in_crate_root() {
     TestResults::new().ok("test::case_1").assert(output);
 }
 
+#[test]
+fn hidden_attribute() {
+    let (output, _) = run_test("export_hidden_template.rs");
+
+    TestResults::new()
+        .ok("public_test::case_1")
+        .ok("private_test::case_1")
+        .ok("foo::test::case_1")
+        .assert(output);
+}
+
+#[test]
+fn hidden_deny_docs() {
+    let (output, _) = run_test("hidden_deny_docs.rs");
+
+    TestResults::new()
+        .ok("public_it_works::case_1")
+        .ok("public_it_works::case_2")
+        .ok("private_it_works::case_1")
+        .ok("private_it_works::case_2")
+        .assert(output);
+}
+
 lazy_static! {
     static ref ROOT_DIR: TempDir = TempDir::new(std::env::temp_dir().join("rstest_reuse"), false);
     static ref ROOT_PROJECT: Project = Project::new(ROOT_DIR.as_ref());

rstest_reuse/tests/resources/export_hidden_template.rs

@@ -0,0 +1,39 @@
+use rstest::rstest;
+use rstest_reuse::apply;
+use rstest_reuse::template;
+
+mod foo {
+    use rstest::rstest;
+    use rstest_reuse::apply;
+    use rstest_reuse::template;
+
+    #[template]
+    #[export]
+    #[hidden]
+    #[rstest]
+    #[case("bar")]
+    fn public_template(#[case] s: &str) {}
+
+    #[apply(public_template)]
+    fn test(#[case] s: &str) {
+        assert_eq!(s, "bar");
+    }
+}
+
+use foo::public_template;
+
+#[apply(public_template)]
+fn public_test(#[case] s: &str) {
+    assert_eq!(s, "bar");
+}
+
+#[template]
+#[hidden]
+#[rstest]
+#[case("bar")]
+fn private_template(#[case] s: &str) {}
+
+#[apply(private_template)]
+fn private_test(#[case] s: &str) {
+    assert_eq!(s, "bar");
+}

rstest_reuse/tests/resources/hidden_deny_docs.rs

@@ -0,0 +1,27 @@
+#![deny(missing_docs)]
+
+//! We should provide also a docs for the crate itself if we set `#![deny(missing_docs)]`.
+
+use rstest::rstest;
+use rstest_reuse::{self, *};
+
+#[template]
+#[export]
+#[hidden]
+#[rstest(a,  b, case(2, 2), case(4/2, 2))]
+fn public_two_simple_cases(a: u32, b: u32) {}
+
+#[apply(public_two_simple_cases)]
+fn public_it_works(a: u32, b: u32) {
+    assert!(a == b);
+}
+
+#[template]
+#[hidden]
+#[rstest(a,  b, case(2, 2), case(4/2, 2))]
+fn private_two_simple_cases(a: u32, b: u32) {}
+
+#[apply(private_two_simple_cases)]
+fn private_it_works(a: u32, b: u32) {
+    assert!(a == b);
+}