From 262bda9be22c2047a19dae3003d82fb4e0e94d5b Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 9 Jan 2026 21:46:09 -0500
Subject: [PATCH 1/2] Revise guideline on unsafe code in macros

Updated guideline on unsafe code in macros to clarify the importance of preserving 'unsafe' token visibility. Added examples of compliant and non-compliant macro implementations.
---
 .../macros/gui_FRLaMIMb4t3S.rst               | 69 ++++++++++++-------
 1 file changed, 44 insertions(+), 25 deletions(-)

diff --git a/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst b/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
index 7fd5a20dc..3f5c42d57 100644
--- a/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
+++ b/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
@@ -3,53 +3,72 @@
 
 .. default-domain:: coding-guidelines
 
-Do not hide unsafe blocks within macro expansions
-=================================================
+Do not hide unsafe code in macros
+================================
 
-.. guideline:: Do not hide unsafe blocks within macro expansions
+.. guideline:: Do not hide unsafe code in macros
    :id: gui_FRLaMIMb4t3S
-   :category: required
+   :category: advisory
    :status: draft
-   :release: todo
+   :release: unclear-latest
    :fls: fls_4vjbkm4ceymk
-   :decidability: todo
-   :scope: todo
-   :tags: reduce-human-error
+   :decidability: decidable
+   :scope: module
+   :tags: safety, reduce-human-error
 
-   Description of the guideline goes here.
+   Do not hide unsafe code in macro definitions.
+   Macros that expand to unsafe code should preserve the ``unsafe`` token visibility.
 
    .. rationale::
-      :id: rat_WJubG7KuUDLW
+      :id: rat_s7ffMlPUFt77
       :status: draft
 
-      Explanation of why this guideline is important.
+      Macros that generate unsafe code obscure safety-critical code, making the code more difficult to review and audit.
 
    .. non_compliant_example::
-      :id: non_compl_ex_AyFnP0lJLHxi
+      :id: non_compl_ex_YNX7AnWENTu7
       :status: draft
 
-      Explanation of code example.
+      Macros that generate unsafe code without preserving the ``unsafe`` token visibility obscure safety-critical code.
+      This noncompliant example defines a ``deref_ptr`` macro that performs an unsafe pointer dereference.
 
       .. rust-example::
 
-        #[allow(dead_code)]
-        fn example_function() {
-            // Non-compliant implementation
+        // This macro hides the unsafe token from callers - noncompliant
+        macro_rules! deref_ptr {
+            ($ptr:expr) => {
+                unsafe { *$ptr }
+            };
+        }
+
+        fn main() {
+            let x = 42;
+            let ptr = &x as *const i32;
+            // The unsafe operation is hidden from the caller
+            println!("val = {}", deref_ptr!(ptr));
         }
-        #
-        # fn main() {}
 
    .. compliant_example::
-      :id: compl_ex_pO5gP1aj2v4F
+      :id: compl_ex_nBkfzueTWvTA
       :status: draft
 
-      Explanation of code example.
+      This compliant example requires the caller to wrap the macro invocation in an ``unsafe`` block,
+      making the use of unsafe code obvious at the call site.
+      Visibility can be further improved by prefixing the identifier for each unsafe macro with the string "unsafe_".
 
       .. rust-example::
 
-        #[allow(dead_code)]
-        fn example_function() {
-            // Compliant implementation
+        // This macro requires the caller to acknowledge the unsafe operation - compliant
+        macro_rules! unsafe_deref_ptr {
+            ($ptr:expr) => {
+                *$ptr
+            };
+        }
+
+        fn main() {
+            let x = 42;
+            let ptr = &x as *const i32;
+            // The unsafe operation is visible at the call site
+            let val = unsafe { unsafe_deref_ptr!(ptr) };
+            println!("val = {}", val);
         }
-        #
-        # fn main() {}

From 84c32f4010aa859e8a9a2354ea6f35efafd3a90c Mon Sep 17 00:00:00 2001
From: Pete LeVasseur <plevasseur@gmail.com>
Date: Mon, 2 Feb 2026 07:03:29 +0900
Subject: [PATCH 2/2] fix: add miri options to macro guideline examples

---
 src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst b/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
index 3f5c42d57..1a745bd8f 100644
--- a/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
+++ b/src/coding-guidelines/macros/gui_FRLaMIMb4t3S.rst
@@ -4,7 +4,7 @@
 .. default-domain:: coding-guidelines
 
 Do not hide unsafe code in macros
-================================
+===================================
 
 .. guideline:: Do not hide unsafe code in macros
    :id: gui_FRLaMIMb4t3S
@@ -33,6 +33,7 @@ Do not hide unsafe code in macros
       This noncompliant example defines a ``deref_ptr`` macro that performs an unsafe pointer dereference.
 
       .. rust-example::
+        :miri:
 
         // This macro hides the unsafe token from callers - noncompliant
         macro_rules! deref_ptr {
@@ -54,9 +55,10 @@ Do not hide unsafe code in macros
 
       This compliant example requires the caller to wrap the macro invocation in an ``unsafe`` block,
       making the use of unsafe code obvious at the call site.
-      Visibility can be further improved by prefixing the identifier for each unsafe macro with the string "unsafe_".
+      Visibility can be further improved by prefixing the identifier for each unsafe macro with the string ``unsafe_``.
 
       .. rust-example::
+        :miri:
 
         // This macro requires the caller to acknowledge the unsafe operation - compliant
         macro_rules! unsafe_deref_ptr {