internal_coverage_positive = rustdoc automation of 2x load of coverage_positive/

Author: peter-lyons-kehl

.gitignore

@@ -3,3 +3,5 @@
 /violations_coverage/in_crate/Cargo.lock
 /violations_coverage/verify_error_messages/target
 /violations_coverage/verify_error_messages/Cargo.lock
+/coverage_*/target
+/coverage_*/Cargo.lock

README.md

@@ -21,7 +21,7 @@ _not_ at runtime/dynamic, but it's done at compile time.) You do it only once pe
 - If you want to apply lints to the macro-generated code (which is highly recommended), your crate
 needs to contain/have access to (a copy of) `prudent`'s file [src/linted.rs](src/linted.rs), which
 you "load" with `::prudent::load!(...)`.
-- If you don't need lints, just `::prudent::load()`.
+- If you don't need lints, just `::prudent::load!()`.
 
 Both ways of `::prudent::load!(...)` create a module, called `prudent` by default. If your crate
 already uses `prudent` identifier, you can choose a different identifier for `prudent`'s top-level
@@ -131,13 +131,14 @@ fn main() {}
 mod module {
   use crate::prudent::unsafe_method;
   // Works for Copy types
-  const _: u8 = unsafe_method!(1u8 =>@ unchecked_add => 0);
-  //const _: u8 = unsafe_method!(({#[forbid(unused)] let v = 1u8; v}), unchecked_add, 0);
-  //const _: u8 = unsafe_method!(#[allow_unsafe] 1u8, unchecked_add, 0);
-  //const _: u8 = unsafe_method!(#[expect_unsafex] 1u8, unchecked_add, 0);
-
-  //const _: u8 = unsafe_method!(({#forbid(unused) let v = 1u8; v}), unchecked_add, 0);
-  const _: u8 = unsafe_method!(~allow_unsafe 1u8 =>@ unchecked_add => 0);
+  const _: u8 = unsafe_method!(                        1u8                    =>@ unchecked_add => 0);
+  const _: u8 = unsafe_method!(~allow_unsafe           1u8                    =>@ unchecked_add => 0);
+  const _: u8 = unsafe_method!(~allow_unsafe  unsafe { 1u8.unchecked_add(2) } =>@ unchecked_add => 0);
+  const _: u8 = unsafe_method!(~expect_unsafe unsafe { 1u8.unchecked_add(2) } =>@ unchecked_add => 0);
+  // @TODO compile_fail:
+  //
+  // const _: u8 = unsafe_method!( unsafe { 1u8.unchecked_add(2) } =>@ unchecked_add => 0);
+  //
   //const _: u8 = unsafe_method!(~expect_unsafe 1u8, unchecked_add, 0);
 }
 fn main() {}
@@ -619,12 +620,20 @@ That IS OK with macros by example (defined with `macro_rules!`), and OK with any
 procedural macros. However, if you pass in an expression that invokes a procedural macro that has
 side effects or state, it's your problem. Such a macro contradicts Rust guidelines.
 
+## unsafe_fn limit max 12 arguments
+
+`unsafe_fn` validates that the function to be called is indeed `unsafe`. It does _not_ use lints to
+validate it, but it uses its own compile time checks instead. Those checks only work with functions
+up to a certain number of arguments. Increasing the limit makes implementation longer (see
+`prudent::unlinted::expecting_unsafe_fn`). For now, the limit is 12. To keep the overall API simple
+enough, those checks can't be turned off.
+
 # Updates
 
 Please subscribe for low frequency updates at
 [peter-lyons-kehl/prudent#1](https://github.com/peter-lyons-kehl/prudent/issues/1).
 
-# Side fruit and related issues
+# Side fruit, related issues, credits
 Please contribute, or at least subscribe, and give thumbs up, to:
 
 ## Related issues
@@ -664,6 +673,11 @@ Sorted by importance (for `prudent`):
 - [dtolnay/trybuild#321](https://github.com/dtolnay/trybuild/pull/321) README: Avoid directory
   traversal
 
+## Credits
+
+Thanks to [Kevin Reid `kpreid`](https://github.com/kpreid) for a tip on [Preamble for doc
+tests...](https://users.rust-lang.org/t/preamble-for-doc-tests-doc-test-attr-or-another-way/136594/2).
+
 <!-- 1. Link URLs to be used on GitHub.
      2. Relative links also work auto-magically on https://crates.io/crates/prudent.
      3. Keep them in the same order as used above.

coverage_positive/fn.rs

@@ -0,0 +1,10 @@
+use crate::prudent::unsafe_fn;
+
+const unsafe fn unsafe_fn_no_args() {}
+const unsafe fn unsafe_fn_one_arg(b: bool) -> bool { b }
+const unsafe fn unsafe_fn_two_args(_: bool, u: u8) -> u8 { u }
+
+const _: () = unsafe_fn!(unsafe_fn_no_args);
+const _: bool = unsafe_fn!(unsafe_fn_one_arg=> true);
+const _: u8 = unsafe_fn!(unsafe_fn_two_args=> true, 0);
+fn main() {}

coverage_positive/md-mut_ref.rs

@@ -0,0 +1,9 @@
+use crate::prudent::unsafe_method;
+// Works for Copy types
+const _: u8 = unsafe_method!(                        1u8                    =>@ unchecked_add => 0);
+const _: u8 = unsafe_method!(~allow_unsafe           1u8                    =>@ unchecked_add => 0);
+const _: u8 = unsafe_method!(~allow_unsafe  unsafe { 1u8.unchecked_add(2) } =>@ unchecked_add => 0);
+const _: u8 = unsafe_method!(~expect_unsafe unsafe { 1u8.unchecked_add(2) } =>@ unchecked_add => 0);
+  
+fn main() {}
+

coverage_positive/md-shared_ref.rs

@@ -23,10 +23,14 @@
 //!    use crate::prudent::*;
 //! ```
 //!
-//! Pass a second parameter, after `->`, if you want the load in a module with name of your choice
+//! Pass a second parameter, after `=>`, if you want the loaded module to have name of your choice
 //! (other than `prudent`).
 #![allow(clippy::useless_attribute)]
 #![allow(clippy::needless_doctest_main)]
+//! # Examples (linted)
+#![doc  = internal_coverage_positive!("any: \"linted.rs\"") ]
+//! # Examples (not linted)
+#![doc  = internal_coverage_positive!("") ]
 #![doc = include_str!("../README.md")]
 #![cfg_attr(not(any(doc, test)), no_std)]
 #![forbid(unknown_lints)]
@@ -79,18 +83,38 @@
 // Workaround for https://github.com/rust-lang/rust/issues/148599
 #![doc(test(attr(allow(forbidden_lint_groups))))]
 
-// Needed, so that macro_rules! in linted.rs can refer to this crate, regardless of whether those
-// macros from linted.rs are accessed as from ::prudent, or loaded with load!() as a module in
-// user crate's namespace.
-//
-//extern crate self as prudent;
-
 #[cfg(doc)]
 extern crate alloc;
 
-//#[cfg(not(doctest))]
-//#[cfg(doctest)]
-//compile_error!("NOT DOCTEST!");
+#[doc(hidden)]
+#[macro_export]
+macro_rules! internal_coverage_positive {
+    (
+        $load_params:literal
+    ) => {
+        $crate::internal_coverage_positive!(
+            $load_params,
+            "unsafe_fn" -> "../coverage_positive/fn.rs",
+            "unsafe_method > self: shared reference" -> "../coverage_positive/md-shared_ref.rs"
+        )
+    };
+    (
+        $load_params:literal,
+        $( $description:literal -> $file:literal ),*
+    ) => {
+        ::core::concat!(
+        $(
+            $description,
+            "\n```\n",
+            "::prudent::load!(", $load_params, ");\n",
+            ::core::include_str!($file),
+            // just in case the file doesn't end with a new line, inject it anyway:
+            "\n```\n",
+        )*
+        "\n"
+        )
+    };
+}
 
 pub mod unlinted;
 
@@ -99,6 +123,7 @@ pub mod unlinted;
 mod linted_untested;
 
 #[path = "linted_with_tests.rs"]
+#[doc(hidden)]
 pub mod linted;
 
 /// No need to be public. The only functionality is macros, which are exported even if private.

coverage_positive/md-value.rs

@@ -124,6 +124,7 @@ macro_rules! internal_prudent_unsafe_fn {
             // `#[deny(unused_unsafe)]` does NOT work here. Why? Because when we assigned `let fun =
             // $fn` above, that then happily coerces/infers to an unsafe function, even though it's
             // safe. That's why we have `expecting_unsafe_fn` module.
+            #[deny(unused_unsafe)]
             #[allow(unsafe_code)]
             let result = unsafe {
                 fun()
@@ -331,8 +332,6 @@ macro_rules! internal_prudent_unsafe_method_internal_check_args_etc {
      ) => {({
                 #[allow(unsafe_code)]
                 // Notify if $self includes `unsafe {...}`, but no ~allow_unsafe or ~expect_unsafe:
-                //
-                //#[deny(unused_unsafe)]
                 #[deny(unused_unsafe)]
                 $(
                     $( { $allow_unsafe_empty_indicator } )?
@@ -342,7 +341,7 @@ macro_rules! internal_prudent_unsafe_method_internal_check_args_etc {
                     $( { $expect_unsafe_empty_indicator } )?
                     #[expect(unused_unsafe)]
                 )?
-                #[deny(unused_unsafe)]
+                //#[deny(unused_unsafe)]
                 let result = unsafe { $self. $fn () };
                 result
     })};

src/lib.rs

@@ -29,27 +29,27 @@ macro_rules! load {
     // Since `any` is **not** specified, this applies to `$[cfg(test)` only.
     ( $prudent_linted_first:literal
       $( $prudent_linted_second:literal )?
-      $( -> $module_name:ident )?
+      $( => $module_name:ident )?
     ) => {
         $crate::load!( ~
             (test) :
             $prudent_linted_first
             $( $prudent_linted_second )?
-            $( -> $module_name )?
+            $( => $module_name )?
         );
     };
     // `any`` means any build/`$cfg`/profile/target...
     ( any :
       $prudent_linted_first:literal
       $( $prudent_linted_second:literal )?
-      $( -> $module_name:ident )?
+      $( => $module_name:ident )?
      ) => {
         // @TODO test:
         $crate::load!( ~
             (test,not(test)) :
              $prudent_linted_first
              $( $prudent_linted_second )?
-             $( -> $module_name )?
+             $( => $module_name )?
         );
     };
     ( ~
@@ -61,45 +61,45 @@ macro_rules! load {
             ( $( $cfg_filter )* ) :
             $prudent_linted_first
             $( $prudent_linted_second )?
-            -> prudent
+            => prudent
         );
       };
     ( ~
       ( $( $cfg_filter:tt )* ) :
       $prudent_linted_same:literal
-      -> $module_name:ident
+      => $module_name:ident
     ) => {
         $crate::load!( ~
             ( $( $cfg_filter )* ) :
             $prudent_linted_same
             $prudent_linted_same
-            -> $module_name
+            => $module_name
         );
     };
     ( ~
       ( $( $cfg_filter:tt )* ) :
       $prudent_linted_first:literal
       $prudent_linted_second:literal
-      -> $module_name:ident
+      => $module_name:ident
     ) => {
         #[cfg(not(windows))]
         $crate::load!( ~~
             ( $( $cfg_filter )* ) :
             $prudent_linted_first
-            -> $module_name
+            => $module_name
         );
 
         #[cfg(windows)]
         $crate::load!( ~~
             ( $( $cfg_filter )* ) :
             $prudent_linted_second
-            -> $module_name
+            => $module_name
         );
     };
     ( ~~
       ( $( $cfg_filter:tt )* ) :
       $prudent_linted:literal
-      -> $module_name:ident
+      => $module_name:ident
     ) => {
         #[cfg(any( $( $cfg_filter )* ))]
         #[allow(unused)]

src/linted.rs

@@ -179,7 +179,6 @@ pub use crate::linted_untested::internal_prudent_unsafe_fn_internal_access_tuple
 #[doc = include_str!("../violations_coverage/unsafe_method/fn_unused_unsafe/some_args.rs")]
 /// ```
 ///
-/// TODO SHOULD FAIL, but it does NOT
 /// ```compile_fail
 #[doc = include_str!("../violations_coverage/unsafe_method/unused_expect_unsafe/zero_args.rs")]
 /// ```