Rollup merge of #66766 - RalfJung:panic-comments, r=SimonSapin

Panic machinery comments and tweaks

This is mostly more comments, but I also renamed some things:
* `BoxMeUp::box_me_up` is not terribly descriptive, and since this is a "take"-style method (the argument is `&mut self` but the return type is fully owned, even though you can't tell from the type) I chose a name involving "take".
* `continue_panic_fmt` was very confusing as it was entirely unclear what was being continued -- for some time I thought "continue" might be the same as "resume" for a panic, but that's something entirely different. So I renamed this to `begin_panic_handler`, matching the `begin_panic*` theme of the other entry points.

r? @Dylan-DPC @SimonSapin

2 files changed, 16 insertions, 5 deletions

diff --git a/src/libcore/panic.rs b/src/libcore/panic.rs
index cdd38449a1b..99b372d92c8 100644
--- a/src/libcore/panic.rs
+++ b/src/libcore/panic.rs
@@ -266,6 +266,16 @@ impl fmt::Display for Location<'_> {
 #[unstable(feature = "std_internals", issue = "0")]
 #[doc(hidden)]
 pub unsafe trait BoxMeUp {
-    fn box_me_up(&mut self) -> *mut (dyn Any + Send);
+    /// Take full ownership of the contents.
+    /// The return type is actually `Box<dyn Any + Send>`, but we cannot use `Box` in libcore.
+    ///
+    /// After this method got called, only some dummy default value is left in `self`.
+    /// Calling this method twice, or calling `get` after calling this method, is an error.
+    ///
+    /// The argument is borrowed because the panic runtime (`__rust_start_panic`) only
+    /// gets a borrowed `dyn BoxMeUp`.
+    fn take_box(&mut self) -> *mut (dyn Any + Send);
+
+    /// Just borrow the contents.
     fn get(&mut self) -> &(dyn Any + Send);
 }
diff --git a/src/libcore/panicking.rs b/src/libcore/panicking.rs
index 4833194be37..5a8d647396d 100644
--- a/src/libcore/panicking.rs
+++ b/src/libcore/panicking.rs
@@ -11,13 +11,13 @@
 //! ```
 //!
 //! This definition allows for panicking with any general message, but it does not
-//! allow for failing with a `Box<Any>` value. The reason for this is that libcore
-//! is not allowed to allocate.
+//! allow for failing with a `Box<Any>` value. (`PanicInfo` just contains a `&(dyn Any + Send)`,
+//! for which we fill in a dummy value in `PanicInfo::internal_constructor`.)
+//! The reason for this is that libcore is not allowed to allocate.
 //!
 //! This module contains a few other panicking functions, but these are just the
 //! necessary lang items for the compiler. All panics are funneled through this
-//! one function. Currently, the actual symbol is declared in the standard
-//! library, but the location of this may change over time.
+//! one function. The actual symbol is declared through the `#[panic_handler]` attribute.
 
 // ignore-tidy-undocumented-unsafe
 
@@ -72,6 +72,7 @@ pub fn panic_fmt(fmt: fmt::Arguments<'_>, location: &Location<'_>) -> ! {
     }
 
     // NOTE This function never crosses the FFI boundary; it's a Rust-to-Rust call
+    // that gets resolved to the `#[panic_handler]` function.
     extern "Rust" {
         #[lang = "panic_impl"]
         fn panic_impl(pi: &PanicInfo<'_>) -> !;