Auto merge of #95655 - kckeiks:create-hir-crate-items-query, r=cjgillot

[rust.git] / library / core / src / macros / panic.md

diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md
index 5127a16bbfd86ed0f8dc164e1b5ef36e94e05490..98fb7e9e41d7a0c2837be360d0fd00d0cbff27c1 100644 (file)
--- 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,35 @@ 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 language provides two complementary systems for constructing /
+representing, reporting, propagating, reacting to, and discarding errors. These
+responsibilities are collectively known as "error handling." `panic!` and
+`Result` are similar in that they are each the primary interface of their
+respective error handling systems; however, the meaning these interfaces attach
+to their errors and the responsibilities they fulfill within their respective
+error handling systems differ.
+
+The `panic!` macro is used to construct errors that represent a bug that has
+been detected in your program. With `panic!` you provide a message that
+describes the bug and the language then constructs an error with that message,
+reports it, and propagates it for you.
+
+`Result` on the other hand is used to wrap other types that represent either
+the successful result of some computation, `Ok(T)`, or error types that
+represent an anticipated runtime failure mode of that computation, `Err(E)`.
+`Result` is used alongside user defined types which represent the various
+anticipated runtime failure modes that the associated computation could
+encounter. `Result` must be propagated manually, often with the the help of the
+`?` operator and `Try` trait, and they must be reported manually, often with
+the help of the `Error` trait.
+
+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 +57,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