Minor docs. Before reverting back to single unsafe_method macro and using if false branching.

Author: peter-lyons-kehl

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "markdownlint.config": {
         "first-line-heading": false,
-        "blanks-around-headings": false
+        "blanks-around-headings": false,
+        "blanks-around-lists": false
     }
 }

README.md

@@ -38,10 +38,14 @@ const fn return_fn_returning_bool() -> fn() -> bool {
 
 # unsafe_method_***
 
-Unfortunately, Rust language limitations don't allow us to have one macro for methods that with
-receiver `self` being a shared reference `&self`, a mutable reference `&mut self` or a value `self`.
-We need to use three different macros: `unsafe_method_ref`, `unsafe_method_mut` and
-`unsafe_method_val`.
+Unfortunately, Rust macros can't have access to the type system. So they can't differentiate whether
+a method's receiver is a shared reference `&self`, a mutable reference `&mut self` or a value
+`self`.
+
+We need to use three different macros:
+- `unsafe_method_ref`,
+- `unsafe_method_mut` and
+- `unsafe_method_val`.
 
 # unsafe_method_ref and unsafe_method_mut in const
 

src/lib.rs

@@ -215,8 +215,9 @@ pub trait AsRefOrMut {
 }
 impl<T> AsRefOrMut for T {}
 
-/// Invoke an unsafe method that has a shared `Self` reference as a receiver: `&self`. Like
-/// [unsafe_fn], but:
+/// Invoke an unsafe method that has a shared reference as a receiver: `&self`.
+///
+/// Like [unsafe_fn], but
 /// - This accepts a receiver `&self`, `&mut self` and `self` (which is then referenced, so it's
 ///   **not** moved/copied).
 /// - This stores `self` in a variable outside of the generated `unsafe {...}`.