From 958bece5e91bd3e248b105edad004be12463a12f Mon Sep 17 00:00:00 2001
From: Ryan Lopopolo <rjl@hyperbo.la>
Date: Mon, 7 Nov 2022 20:33:20 -0800
Subject: [PATCH] Improve documentation in `raise` module

- Improve safety comment on `ExceptionPayload` unsafe impl
- Document why `panic::resume_unwind` is used instead of `panic_any!`
---
 artichoke-backend/src/raise.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/artichoke-backend/src/raise.rs b/artichoke-backend/src/raise.rs
index 9211d192c0fd..b1a5080b35d6 100644
--- a/artichoke-backend/src/raise.rs
+++ b/artichoke-backend/src/raise.rs
@@ -14,7 +14,7 @@ struct ExceptionPayload {
     inner: Value,
 }
 
-// SAFETY:
+// SAFETY: this panic payload never crosses a thread boundary.
 //
 // - mruby is single threaded and cannot be `Send`.
 // - This struct is used directly in `std::panic::resume_unwind` and is not used
@@ -33,6 +33,8 @@ unsafe impl Send for ExceptionPayload {}
 #[no_mangle]
 unsafe extern "C-unwind" fn artichoke_exc_throw(mrb: *mut sys::mrb_state, exc: sys::mrb_value) -> ! {
     let _ = mrb;
+    // Use `panic::resume_unwind` instead of `panic_any!` here to avoid running
+    // the built-in panic hook and printing stack to stderr.
     panic::resume_unwind(Box::new(ExceptionPayload {
         inner: Value::from(exc),
     }));