Rollup merge of #95660 - yaahc:panic-docs-update, r=Dylan-DPC

Update panic docs to make it clearer when to use panic vs Result

This is based on a question that came up in one of my [error handling office hours](https://twitter.com/yaahc_/status/1506376624509374467?s=20&t=Sp-cEjrx5kpMdNsAGPOo9w) meetings. I had a user who was fairly familiar with error type design, thiserror and anyhow, and rust in general, but who was still confused about when to use panics vs when to use Result and `Error`.

This will also be cross referenced in an error handling FAQ that I will be creating in the https://github.com/rust-lang/project-error-handling repo shortly.

1 files changed, 19 insertions, 7 deletions

diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md
index 5127a16bbfd..d8206e78931 100644
--- a/library/core/src/macros/panic.md
+++ b/library/core/src/macros/panic.md
@@ -1,8 +1,7 @@
 Panics the current thread.
 
 This allows a program to terminate immediately and provide feedback
-to the caller of the program. `panic!` should be used when a program reaches
-an unrecoverable state.
+to the caller of the program.
 
 This macro is the perfect way to assert conditions in example code and in
 tests. `panic!` is closely tied with the `unwrap` method of both
@@ -21,13 +20,25 @@ Inside the hook a panic can be accessed as a `&dyn Any + Send`,
 which contains either a `&str` or `String` for regular `panic!()` invocations.
 To panic with a value of another other type, [`panic_any`] can be used.
 
-[`Result`] enum is often a better solution for recovering from errors than
-using the `panic!` macro. This macro should be used to avoid proceeding using
-incorrect values, such as from external sources. Detailed information about
-error handling is found in the [book].
-
 See also the macro [`compile_error!`], for raising errors during compilation.
 
+# When to use `panic!` vs `Result`
+
+The Rust model of error handling groups errors into two major categories:
+recoverable and unrecoverable errors. For a recoverable error, such as a file
+not found error, it’s reasonable to report the problem to the user and retry
+the operation. Unrecoverable errors are always symptoms of bugs, like trying to
+access a location beyond the end of an array.
+
+The Rust language and standard library provides `Result` and `panic!` as parts
+of two complementary systems for representing, reporting, propagating, reacting
+to, and discarding errors for in these two categories.
+
+The `panic!` macro is provided to represent unrecoverable errors, whereas the
+`Result` enum is provided to represent recoverable errors. For more detailed
+information about error handling check out the [book] or the [`std::result`]
+module docs.
+
 [ounwrap]: Option::unwrap
 [runwrap]: Result::unwrap
 [`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html
@@ -36,6 +47,7 @@ See also the macro [`compile_error!`], for raising errors during compilation.
 [`Any`]: crate::any::Any
 [`format!`]: ../std/macro.format.html
 [book]: ../book/ch09-00-error-handling.html
+[`std::result`]: ../std/result/index.html
 
 # Current implementation