From 4413c52a9d15dab63cec96b7e654d45b95ec4c60 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Mon, 3 Jun 2019 22:25:20 -0700 Subject: [PATCH 1/2] Centralize panic macro documentation --- src/libcore/{macros.rs => macros/mod.rs} | 4 +- src/libcore/macros/panic.md | 47 +++++++++++++++++++++++ src/libstd/macros.rs | 48 +----------------------- 3 files changed, 49 insertions(+), 50 deletions(-) rename src/libcore/{macros.rs => macros/mod.rs} (99%) create mode 100644 src/libcore/macros/panic.md diff --git a/src/libcore/macros.rs b/src/libcore/macros/mod.rs similarity index 99% rename from src/libcore/macros.rs rename to src/libcore/macros/mod.rs index 218c164a7dc35..77c126858b03f 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros/mod.rs @@ -1,6 +1,4 @@ -/// Panics the current thread. -/// -/// For details, see `std::macros`. +#[doc(include = "panic.md")] #[macro_export] #[allow_internal_unstable(core_panic, __rust_unstable_column)] #[stable(feature = "core", since = "1.6.0")] diff --git a/src/libcore/macros/panic.md b/src/libcore/macros/panic.md new file mode 100644 index 0000000000000..3ecfc43be049b --- /dev/null +++ b/src/libcore/macros/panic.md @@ -0,0 +1,47 @@ +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. + +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 [`Option`] +and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set +to None or Err variants. + +This macro is used to inject panic into a Rust thread, causing the thread to +panic entirely. Each thread's panic can be reaped as the `Box` type, +and the single-argument form of the `panic!` macro will be the value which +is transmitted. + +[`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]. + +The multi-argument form of this macro panics with a string and has the +[`format!`] syntax for building a string. + +See also the macro [`compile_error!`], for raising errors during compilation. + +[runwrap]: ../std/result/enum.Result.html#method.unwrap +[`Option`]: ../std/option/enum.Option.html#method.unwrap +[`Result`]: ../std/result/enum.Result.html +[`format!`]: ../std/macro.format.html +[`compile_error!`]: ../std/macro.compile_error.html +[book]: ../book/ch09-00-error-handling.html + +# Current implementation + +If the main thread panics it will terminate all your threads and end your +program with code `101`. + +# Examples + +```should_panic +# #![allow(unreachable_code)] +panic!(); +panic!("this is a terrible mistake!"); +panic!(4); // panic with the value of 4 to be collected elsewhere +panic!("this is a {} {message}", "fancy", message = "message"); +``` diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 839b4c5656a09..d16a6e4a44e81 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -4,53 +4,7 @@ //! library. Each macro is available for use when linking against the standard //! library. -/// 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. -/// -/// 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 [`Option`] -/// and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set -/// to None or Err variants. -/// -/// This macro is used to inject panic into a Rust thread, causing the thread to -/// panic entirely. Each thread's panic can be reaped as the `Box` type, -/// and the single-argument form of the `panic!` macro will be the value which -/// is transmitted. -/// -/// [`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]. -/// -/// The multi-argument form of this macro panics with a string and has the -/// [`format!`] syntax for building a string. -/// -/// See also the macro [`compile_error!`], for raising errors during compilation. -/// -/// [runwrap]: ../std/result/enum.Result.html#method.unwrap -/// [`Option`]: ../std/option/enum.Option.html#method.unwrap -/// [`Result`]: ../std/result/enum.Result.html -/// [`format!`]: ../std/macro.format.html -/// [`compile_error!`]: ../std/macro.compile_error.html -/// [book]: ../book/ch09-00-error-handling.html -/// -/// # Current implementation -/// -/// If the main thread panics it will terminate all your threads and end your -/// program with code `101`. -/// -/// # Examples -/// -/// ```should_panic -/// # #![allow(unreachable_code)] -/// panic!(); -/// panic!("this is a terrible mistake!"); -/// panic!(4); // panic with the value of 4 to be collected elsewhere -/// panic!("this is a {} {message}", "fancy", message = "message"); -/// ``` +#[doc(include = "../libcore/macros/panic.md")] #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] #[allow_internal_unstable(__rust_unstable_column, libstd_sys_internals)] From 421d9ea1bd462133341e0b906d60cd0fea82d3f3 Mon Sep 17 00:00:00 2001 From: Chris Gregory Date: Tue, 4 Jun 2019 06:31:58 -0700 Subject: [PATCH 2/2] Fix link in core --- src/libcore/macros/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/macros/mod.rs b/src/libcore/macros/mod.rs index 77c126858b03f..a2ac34d2a42de 100644 --- a/src/libcore/macros/mod.rs +++ b/src/libcore/macros/mod.rs @@ -1,4 +1,4 @@ -#[doc(include = "panic.md")] +#[doc(include = "macros/panic.md")] #[macro_export] #[allow_internal_unstable(core_panic, __rust_unstable_column)] #[stable(feature = "core", since = "1.6.0")]