Tests and docs

Author: peter-lyons-kehl

src/lib.rs

@@ -4,7 +4,12 @@
 // code generated by this crate's macros. (https://github.com/rust-lang/nomicon/issues/506)
 #![cfg_attr(not(any(doc, test)), forbid(unsafe_code))]
 #![forbid(unknown_lints)]
-#![forbid(unused, dead_code)]
+// We can't `#![forbid(dead_code)]`, because we use `#[allow(unused_unsafe)]`. Without that
+// unsafe_method! existed only as multiple specialized macros: unsafe_method_ref!,
+// unsafe_method_mut!... And there were problems with unintended duplicates of Copy `self` when
+// invoking methods with the receiver being &self, that is, a shared reference.
+#![deny(unused)]
+#![forbid(dead_code)]
 // docs
 #![forbid(missing_docs)]
 // rustdoc lints: https://doc.rust-lang.org/rustdoc/lints.html
@@ -73,13 +78,22 @@ extern crate alloc;
 #[doc = include_str!("../violations_coverage/unsafe_fn/some_args/arg.rs")]
 /// ```
 /// ```
+/// # // @TODO
 /// # use prudent::unsafe_fn;
 /// unsafe fn return_array() -> [bool; 1] {
 ///     [true]
 /// }
 ///
 /// let _b = unsafe_fn!( return_array)[0];
 /// ```
+/// ```no_run
+/// # use prudent::unsafe_fn;
+/// unsafe fn return_mut_ref_array() -> &'static mut [bool; 1] {
+///     unreachable!()
+/// }
+///
+/// unsafe_fn!( return_mut_ref_array)[0] = true;
+/// ```
 #[macro_export]
 macro_rules! unsafe_fn {
     ( $fn:expr $(, $arg:expr)* ) => {
@@ -131,6 +145,9 @@ pub const _: () = {};
 /// - This treats `self` as if it were evaluated **outside** the `unsafe {...}` block.
 /// - $fn can **NOT** be an expression or a qualified path (which doesn't work in standard methods
 ///   calls anyways), but only an identifier.
+/// ```compile_fail
+#[doc = include_str!("../violations_coverage/unsafe_method/some_args/arg.rs")]
+/// ```
 #[macro_export]
 macro_rules! unsafe_method {
     ($self:expr, $fn:ident $(, $arg:expr)* ) => {
@@ -143,11 +160,25 @@ macro_rules! unsafe_method {
                 unreachable!()
             } else {
                 #[allow(unsafe_code)]
+                //@TODO: for unsafe_fn, too:
+                //
+                // If $self or any $arg include `unsafe {...}`, that would trigger "unused_unsafe".
+                //
+                // Unfortunately, because of this, we can't detect code where unsafe_fn! or
+                // unsafe_method! is not needed at all. For example, if a function/method use to be
+                // `unsafe`, and it stopped being so.
+                #[allow(unused_unsafe)]
                 unsafe { $self. $fn ( $( $arg ),* ) }
             }
         }
     };
 }
+/// ```compile_fail,E0133
+#[doc = include_str!("../violations_coverage/unsafe_method/some_args/arg.rs")]
+/// ```
+#[cfg(doctest)]
+pub const _: () = {};
+
 //-------------
 
 /// Set a value of a `static mut` variable or its (sub...-)field, but isolate `unsafe {...}` only to
@@ -189,7 +220,7 @@ macro_rules! unsafe_method {
 ///     *_mref = [false];
 ///     _mref[ 0 ] = true;
 ///     
-///     // Read accesss OK:
+///     // Read access OK:
 ///     let _b: bool = { unsafe {&mut *mptr} }[ 0 ];
 ///     // Mut access - bad: The following refused:
 ///     //

violations_coverage/fn_add_four/Cargo.lock

@@ -0,0 +1 @@
+../../../unsafe_method/some_args/arg.rs

violations_coverage/fn_add_four/Cargo.toml

@@ -0,0 +1,5 @@
+use prudent::unsafe_method;
+
+fn main() {
+    let _ = unsafe_method!(1u8, unchecked_add, 0u8.unchecked_add(0));
+}