From b41b2e5a5cb9aa3d56dd2da23c2438d16fef9997 Mon Sep 17 00:00:00 2001
From: Ed Morley <501702+edmorley@users.noreply.github.com>
Date: Thu, 11 Nov 2021 13:41:21 +0000
Subject: [PATCH] Document `unreachable!()` custom panic message

The `unreachable!` docs previously did not mention that there was a second
form, `unreachable!("message")` that could be used to specify a custom panic
message,

The docs now mention this in the same style as currently used for `unimplemented!`:
https://doc.rust-lang.org/core/macro.unimplemented.html#panics
---
 library/core/src/macros/mod.rs | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs
index 5b3e988caa506..993ae72322966 100644
--- a/library/core/src/macros/mod.rs
+++ b/library/core/src/macros/mod.rs
@@ -554,7 +554,10 @@ macro_rules! writeln {
 ///
 /// # Panics
 ///
-/// This will always [`panic!`].
+/// This will always [`panic!`] because `unreachable!` is just a shorthand for `panic!` with a
+/// fixed, specific message.
+///
+/// Like `panic!`, this macro has a second form for displaying custom values.
 ///
 /// # Examples
 ///
@@ -581,7 +584,7 @@ macro_rules! writeln {
 ///         if 3*i < i { panic!("u32 overflow"); }
 ///         if x < 3*i { return i-1; }
 ///     }
-///     unreachable!();
+///     unreachable!("The loop should always return");
 /// }
 /// ```
 #[macro_export]