From cca865dd137e251458e18d566dc73d6870a5a8ec Mon Sep 17 00:00:00 2001
From: Mara Bos <m-ou.se@m-ou.se>
Date: Mon, 2 Oct 2023 14:12:37 +0200
Subject: [PATCH] Update doc comment about core::panicking.

---
 core/src/panicking.rs | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/core/src/panicking.rs b/core/src/panicking.rs
index 683894a5ab49f..aa11ae28dcb15 100644
--- a/core/src/panicking.rs
+++ b/core/src/panicking.rs
@@ -1,7 +1,14 @@
 //! Panic support for core
 //!
-//! The core library cannot define panicking, but it does *declare* panicking. This
-//! means that the functions inside of core are allowed to panic, but to be
+//! In core, panicking is always done with a message, resulting in a core::panic::PanicInfo
+//! containing a fmt::Arguments. In std, however, panicking can be done with panic_any, which throws
+//! a Box<dyn Any> containing any type of value. Because of this, std::panic::PanicInfo is a
+//! different type, which contains a &dyn Any instead of a fmt::Arguments.
+//! std's panic handler will convert the fmt::Arguments to a &dyn Any containing either a
+//! &'static str or String containing the formatted message.
+//!
+//! The core library cannot define any panic handler, but it can invoke it.
+//! This means that the functions inside of core are allowed to panic, but to be
 //! useful an upstream crate must define panicking for core to use. The current
 //! interface for panicking is:
 //!
@@ -10,11 +17,6 @@
 //! # { loop {} }
 //! ```
 //!
-//! This definition allows for panicking with any general message, but it does not
-//! 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 core 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. The actual symbol is declared through the `#[panic_handler]` attribute.