Doc/Doctests

Author: peter-lyons-kehl

README.md

@@ -104,46 +104,6 @@ Following are all the positive examples. They are also run by the above [GitHub
 For negative examples, which catch unintended `unsafe` functions/expressions/access, see
 documentation of each `prudent` macro.
 
-# unsafe_fn
-```rust
-// @TODO both any: and default:
-::prudent::load!(any: "linted.rs");
-//::prudent::load!();
-
-//use crate::prudent::*;
-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() {}
-```
-
-# unsafe_method
-## unsafe_method > self: shared reference
-```rust
-//::prudent::load!(any: "linted.rs");
-::prudent::load!();
-mod module {
-  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);
-  // @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() {}
-```
-
 ```rust
 let _todo = ();
 //# use prudent::unsafe_method;
@@ -168,7 +128,7 @@ impl SNonCopy {
 
 fn main() {
     let s = SNonCopy {};
-    // Works for non-Copy types
+    // Works ALSO for non-Copy types
     unsafe_method!(s =>@ unsafe_method_no_args);
     unsafe_method!(s =>@ unsafe_method_one_arg => true);
     unsafe_method!(s =>@ unsafe_method_two_args => true, false);

src/lib.rs

@@ -24,7 +24,11 @@
 //! ```
 //!
 //! Pass a second parameter, after `=>`, if you want the loaded module to have name of your choice
-//! (other than `prudent`).
+//! (other than `prudent`). For example:
+//! ```ignore
+//!    ::prudent::load!("../../prudent/src/linted.rs" => prudentish);
+//!    use crate::prudentish::*;
+//! ```
 #![allow(clippy::useless_attribute)]
 #![allow(clippy::needless_doctest_main)]
 //! # Examples (linted)
@@ -94,8 +98,8 @@ macro_rules! internal_coverage_positive {
     ) => {
         $crate::internal_coverage_positive!(
             $load_params,
-            "unsafe_fn" -> "../coverage_positive/fn.rs",
-            "unsafe_method > self: shared reference" -> "../coverage_positive/md-shared_ref.rs"
+            "# unsafe_fn" -> "../coverage_positive/fn.rs",
+            "# unsafe_method\n## unsafe_method > self: shared reference" -> "../coverage_positive/md-shared_ref.rs"
         )
     };
     (

src/linted.rs

@@ -247,8 +247,8 @@ macro_rules! internal_prudent_unsafe_method {
                     $( ~expect_unsafe $( { $expect_unsafe_empty_indicator } )? )?
                 }
                 if false {
-                    // This block "makes" owned_receiver, an instance/owned value of the same type
-                    // as $self. (Of course, the instance is invalid - this is for compile-time
+                    // This block "makes" an owned_receiver, an instance/owned value of the same
+                    // type as $self. (Of course, the instance is invalid - this is for compile-time
                     // checks only, hence `if false {...}`.)
                     //
                     // Then we simulate invocation of the given method inside `unsafe {...}``, BUT
@@ -277,7 +277,7 @@ macro_rules! internal_prudent_unsafe_method {
                         ::prudent::unlinted::shared_to_mut( rref )
                     };
                     #[allow(unused_mut)]
-                    #[allow(invalid_value)]
+                    #[allow(invalid_value)] // for &str and other types where zeroed() issues invalid_value warning.
                     let mut owned_receiver = ::core::mem::replace(mref, unsafe{ ::core::mem::zeroed() });
                     // Detect code where unsafe_fn! or unsafe_method! is not needed at all. That is,
                     // where a function/method used to be `unsafe`, but it stopped being so.
@@ -394,9 +394,10 @@ macro_rules! internal_prudent_unsafe_method_internal_build_accessors_check_args_
         )?
         let result = unsafe {
             // Unlike arguments, we can NOT store result of $self expression in a variable, because
-            // it would be moved, but a method with receiver by reference `&self` or `&mut self`
-            // does NOT move the instance it's called on. And if Self were `Copy`, then the
-            // reference would not point to the original instance!
+            // - it would be moved, but a method with receiver by reference `&self` or `&mut self`
+            // does NOT move the instance it's called on. Also,
+            // - if Self were `Copy`, then `&self` or `&mut self` reference would not point to the
+            //   original instance! (Plus extra stack used, plus lifetimes issues.)
             $self. $fn( $(
                     internal_prudent_unsafe_fn_internal_access_tuple_tree_field!{ $tuple_tree, $($accessor_part),+ }
                 ),*