From 686a31eaaa1feb78bbb52845752426b130a0fd51 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 13 Apr 2022 19:08:10 -0700 Subject: [PATCH 01/12] Add section on common message styles for Result::expect --- core/src/result.rs | 56 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/core/src/result.rs b/core/src/result.rs index b2b132300..564e5e34d 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1023,6 +1023,62 @@ impl Result { /// let x: Result = Err("emergency failure"); /// x.expect("Testing expect"); // panics with `Testing expect: emergency failure` /// ``` + /// + /// # Common Message Styles + /// + /// There are two common styles for how people word `expect` messages. Using the message to + /// present information to users encountering a panic ("expect as error message") or using the + /// message to present information to developers debugging the panic ("expect as + /// precondition"). + /// + /// In the former case the expect message is used to describe the error that has occurred which + /// is considered a bug. Consider the following example: + /// + /// ``` + /// // Read environment variable, panic if it is not present + /// let path = std::env::var("IMPORTANT_PATH").unwrap(); + /// ``` + /// + /// In the "expect as error message" style we would use expect to describe that the environment + /// variable was not set when it should have been: + /// + /// ``` + /// let path = std::env::var("IMPORTANT_PATH") + /// .expect("env variable `IMPORTANT_PATH` is not set"); + /// ``` + /// + /// In the latter style, we would instead describe the reason we _expect_ the `Result` will + /// always be `Ok`. With this style we would instead write: + /// + /// ``` + /// let path = std::env::var("IMPORTANT_PATH") + /// .expect("env variable `IMPORTANT_PATH` is always be set by `wrapper_script.sh`"); + /// ``` + /// + /// The "expect as error message" style has the advantage of giving a more user friendly error + /// message, and is more consistent with the default output of the [panic hook] provided by + /// `std`. + /// + /// ``` + /// thread 'expect_as_error_message' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/lib.rs:4:10 + /// ``` + /// + /// The "expect as precondition" style instead focuses on source code readability, making it + /// easier to understand what must have gone wrong in situations where panics are being used to + /// represent bugs exclusively. But this extra information often looks confusing when presented + /// directly to users with the default `std` panic hook's report format: + /// + /// ``` + /// thread 'expect_as_precondition' panicked at 'env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`: NotPresent', src/lib.rs:4:10 + /// ``` + /// + /// This style works best when paired with a custom [panic hook] like the one provided by the + /// CLI working group library, [`human-panic`], which redirects panic messages to crash report + /// files while showing users a more "Oops, something went wrong!" message with a suggestion to + /// send the crash report file back to the developers. + /// + /// [panic hook]: https://doc.rust-lang.org/stable/std/panic/fn.set_hook.html + /// [`human-panic`]: https://docs.rs/human-panic #[inline] #[track_caller] #[stable(feature = "result_expect", since = "1.4.0")] From 46b0b4a7be7caf1232b3b40365b15cc8c0884c17 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 14 Apr 2022 11:40:27 -0700 Subject: [PATCH 02/12] add necessary text attribute to code block of panic output --- core/src/result.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/src/result.rs b/core/src/result.rs index 564e5e34d..6189000cd 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1059,7 +1059,7 @@ impl Result { /// message, and is more consistent with the default output of the [panic hook] provided by /// `std`. /// - /// ``` + /// ```text /// thread 'expect_as_error_message' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/lib.rs:4:10 /// ``` /// @@ -1068,7 +1068,7 @@ impl Result { /// represent bugs exclusively. But this extra information often looks confusing when presented /// directly to users with the default `std` panic hook's report format: /// - /// ``` + /// ```text /// thread 'expect_as_precondition' panicked at 'env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`: NotPresent', src/lib.rs:4:10 /// ``` /// From d683b6383427b9439d5ca6e00b256bf20e26d8fe Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 14 Apr 2022 13:22:24 -0700 Subject: [PATCH 03/12] add should_panic annotations --- core/src/result.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/core/src/result.rs b/core/src/result.rs index 6189000cd..8a68e3fe6 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1034,7 +1034,7 @@ impl Result { /// In the former case the expect message is used to describe the error that has occurred which /// is considered a bug. Consider the following example: /// - /// ``` + /// ```should_panic /// // Read environment variable, panic if it is not present /// let path = std::env::var("IMPORTANT_PATH").unwrap(); /// ``` @@ -1042,7 +1042,7 @@ impl Result { /// In the "expect as error message" style we would use expect to describe that the environment /// variable was not set when it should have been: /// - /// ``` + /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") /// .expect("env variable `IMPORTANT_PATH` is not set"); /// ``` @@ -1050,7 +1050,7 @@ impl Result { /// In the latter style, we would instead describe the reason we _expect_ the `Result` will /// always be `Ok`. With this style we would instead write: /// - /// ``` + /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") /// .expect("env variable `IMPORTANT_PATH` is always be set by `wrapper_script.sh`"); /// ``` From 79bfea708fabe7236395beb4416a0d704ae4f899 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 15 Apr 2022 10:24:34 -0700 Subject: [PATCH 04/12] update docs for option to crossreference to the result docs --- core/src/option.rs | 3 +++ core/src/result.rs | 14 +++++++------- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/core/src/option.rs b/core/src/option.rs index 91e4708f6..f280c321c 100644 --- a/core/src/option.rs +++ b/core/src/option.rs @@ -708,6 +708,9 @@ impl Option { /// let x: Option<&str> = None; /// x.expect("fruits are healthy"); // panics with `fruits are healthy` /// ``` + /// + /// **Note**: Please refer to the documentation on [`Result::expect`] for further information + /// on common message styles. #[inline] #[track_caller] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/core/src/result.rs b/core/src/result.rs index 8a68e3fe6..7cbe2213b 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1047,8 +1047,8 @@ impl Result { /// .expect("env variable `IMPORTANT_PATH` is not set"); /// ``` /// - /// In the latter style, we would instead describe the reason we _expect_ the `Result` will - /// always be `Ok`. With this style we would instead write: + /// In the "expect as precondition" style, we would instead describe the reason we _expect_ the + /// `Result` will always be `Ok`. With this style we would prefer to write: /// /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") @@ -1060,7 +1060,7 @@ impl Result { /// `std`. /// /// ```text - /// thread 'expect_as_error_message' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/lib.rs:4:10 + /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/main.rs:4:6 /// ``` /// /// The "expect as precondition" style instead focuses on source code readability, making it @@ -1069,13 +1069,13 @@ impl Result { /// directly to users with the default `std` panic hook's report format: /// /// ```text - /// thread 'expect_as_precondition' panicked at 'env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`: NotPresent', src/lib.rs:4:10 + /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is always be set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 /// ``` /// /// This style works best when paired with a custom [panic hook] like the one provided by the - /// CLI working group library, [`human-panic`], which redirects panic messages to crash report - /// files while showing users a more "Oops, something went wrong!" message with a suggestion to - /// send the crash report file back to the developers. + /// CLI working group library, [`human-panic`], which dumps the panic messages to a crash + /// report file while showing users a more friendly "Oops, something went wrong!" message with + /// a suggestion to send the crash report file back to the developers. /// /// [panic hook]: https://doc.rust-lang.org/stable/std/panic/fn.set_hook.html /// [`human-panic`]: https://docs.rs/human-panic From cd95d58b13207d8233b7bc5909f1e74c900d7308 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 18 Apr 2022 16:31:13 -0700 Subject: [PATCH 05/12] Update library/core/src/result.rs Co-authored-by: Emil Thorenfeldt --- core/src/result.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/src/result.rs b/core/src/result.rs index 7cbe2213b..47e718b6a 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1052,7 +1052,7 @@ impl Result { /// /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") - /// .expect("env variable `IMPORTANT_PATH` is always be set by `wrapper_script.sh`"); + /// .expect("env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`"); /// ``` /// /// The "expect as error message" style has the advantage of giving a more user friendly error From 43a8c151e3070cddd0ec0eeb5e4fc1b4d7675a87 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 18 Apr 2022 16:31:21 -0700 Subject: [PATCH 06/12] Update library/core/src/result.rs Co-authored-by: Emil Thorenfeldt --- core/src/result.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/src/result.rs b/core/src/result.rs index 47e718b6a..040977585 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1069,7 +1069,7 @@ impl Result { /// directly to users with the default `std` panic hook's report format: /// /// ```text - /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is always be set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 + /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 /// ``` /// /// This style works best when paired with a custom [panic hook] like the one provided by the From 32cc5d591f1a9a4bd69433f30ec025b30afb70c1 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Sat, 30 Apr 2022 03:04:31 +0000 Subject: [PATCH 07/12] spicy --- core/src/result.rs | 68 +++++++++++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/core/src/result.rs b/core/src/result.rs index 040977585..99d39b701 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1026,56 +1026,74 @@ impl Result { /// /// # Common Message Styles /// - /// There are two common styles for how people word `expect` messages. Using the message to - /// present information to users encountering a panic ("expect as error message") or using the - /// message to present information to developers debugging the panic ("expect as - /// precondition"). + /// There are two common styles for how people word `expect` messages. Using + /// the message to present information to users encountering a panic + /// ("expect as error message") or using the message to present information + /// to developers debugging the panic ("expect as precondition"). /// - /// In the former case the expect message is used to describe the error that has occurred which - /// is considered a bug. Consider the following example: + /// In the former case the expect message is used to describe the error that + /// has occurred which is considered a bug. Consider the following example: /// /// ```should_panic /// // Read environment variable, panic if it is not present /// let path = std::env::var("IMPORTANT_PATH").unwrap(); /// ``` /// - /// In the "expect as error message" style we would use expect to describe that the environment - /// variable was not set when it should have been: + /// In the "expect as error message" style we would use expect to describe + /// that the environment variable was not set when it should have been: /// /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") /// .expect("env variable `IMPORTANT_PATH` is not set"); /// ``` /// - /// In the "expect as precondition" style, we would instead describe the reason we _expect_ the - /// `Result` will always be `Ok`. With this style we would prefer to write: + /// In the "expect as precondition" style, we would instead describe the + /// reason we _expect_ the `Result` should be `Ok`. With this style we would + /// prefer to write: /// /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") - /// .expect("env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`"); + /// .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); /// ``` /// - /// The "expect as error message" style has the advantage of giving a more user friendly error - /// message, and is more consistent with the default output of the [panic hook] provided by - /// `std`. + /// The "expect as error message" style does not work as well with the + /// default output of the std panic hooks, and often ends up repeating + /// information that is already communicated by the source error being + /// unwrapped: /// /// ```text /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/main.rs:4:6 /// ``` /// - /// The "expect as precondition" style instead focuses on source code readability, making it - /// easier to understand what must have gone wrong in situations where panics are being used to - /// represent bugs exclusively. But this extra information often looks confusing when presented - /// directly to users with the default `std` panic hook's report format: + /// In this example we end up mentioning that an env variable is not set, + /// followed by our source message that says the env is not present, the + /// only additional information we're communicating is the name of the + /// environment variable being checked. /// - /// ```text - /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is always set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 - /// ``` + /// The "expect as precondition" style instead focuses on source code + /// readability, making it easier to understand what must have gone wrong in + /// situations where panics are being used to represent bugs exclusively. + /// Also, by framing our expect in terms of what "SHOULD" have happened to + /// prevent the source error, we end up introducing new information that is + /// independent from our source error. /// - /// This style works best when paired with a custom [panic hook] like the one provided by the - /// CLI working group library, [`human-panic`], which dumps the panic messages to a crash - /// report file while showing users a more friendly "Oops, something went wrong!" message with - /// a suggestion to send the crash report file back to the developers. + /// ```text + /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 + /// ``` + /// + /// In this example we are communicating not only the name of the + /// environment variable that should have been set, but also an explanation + /// for why it should have been set, and we let the source error display as + /// a clear contradiction to our expectation. + /// + /// For programs where panics may be user facing, either style works best + /// when paired with a custom [panic hook] like the one provided by the CLI + /// working group library, [`human-panic`]. This panic hook dumps the panic + /// messages to a crash report file while showing users a more friendly + /// "Oops, something went wrong!" message with a suggestion to send the + /// crash report file back to the developers. Panic messages should be used + /// to represent bugs, and the information provided back is context intended + /// for the developer, not the user. /// /// [panic hook]: https://doc.rust-lang.org/stable/std/panic/fn.set_hook.html /// [`human-panic`]: https://docs.rs/human-panic From dd827256dd518558fcd8a466789ff1c8dfdeed43 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 6 May 2022 15:03:25 -0700 Subject: [PATCH 08/12] This is a pretty good start if you ask me --- core/src/result.rs | 72 ++---------------------- std/src/error.rs | 133 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 138 insertions(+), 67 deletions(-) diff --git a/core/src/result.rs b/core/src/result.rs index 99d39b701..342acea29 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1024,79 +1024,19 @@ impl Result { /// x.expect("Testing expect"); // panics with `Testing expect: emergency failure` /// ``` /// - /// # Common Message Styles + /// # Recommended Message Style /// - /// There are two common styles for how people word `expect` messages. Using - /// the message to present information to users encountering a panic - /// ("expect as error message") or using the message to present information - /// to developers debugging the panic ("expect as precondition"). - /// - /// In the former case the expect message is used to describe the error that - /// has occurred which is considered a bug. Consider the following example: - /// - /// ```should_panic - /// // Read environment variable, panic if it is not present - /// let path = std::env::var("IMPORTANT_PATH").unwrap(); - /// ``` - /// - /// In the "expect as error message" style we would use expect to describe - /// that the environment variable was not set when it should have been: - /// - /// ```should_panic - /// let path = std::env::var("IMPORTANT_PATH") - /// .expect("env variable `IMPORTANT_PATH` is not set"); - /// ``` - /// - /// In the "expect as precondition" style, we would instead describe the - /// reason we _expect_ the `Result` should be `Ok`. With this style we would - /// prefer to write: + /// We recommend that `expect` messages are used to describe the reason you + /// _expect_ the `Result` should be `Ok`. /// /// ```should_panic /// let path = std::env::var("IMPORTANT_PATH") /// .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); /// ``` /// - /// The "expect as error message" style does not work as well with the - /// default output of the std panic hooks, and often ends up repeating - /// information that is already communicated by the source error being - /// unwrapped: - /// - /// ```text - /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/main.rs:4:6 - /// ``` - /// - /// In this example we end up mentioning that an env variable is not set, - /// followed by our source message that says the env is not present, the - /// only additional information we're communicating is the name of the - /// environment variable being checked. - /// - /// The "expect as precondition" style instead focuses on source code - /// readability, making it easier to understand what must have gone wrong in - /// situations where panics are being used to represent bugs exclusively. - /// Also, by framing our expect in terms of what "SHOULD" have happened to - /// prevent the source error, we end up introducing new information that is - /// independent from our source error. - /// - /// ```text - /// thread 'main' panicked at 'env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 - /// ``` - /// - /// In this example we are communicating not only the name of the - /// environment variable that should have been set, but also an explanation - /// for why it should have been set, and we let the source error display as - /// a clear contradiction to our expectation. - /// - /// For programs where panics may be user facing, either style works best - /// when paired with a custom [panic hook] like the one provided by the CLI - /// working group library, [`human-panic`]. This panic hook dumps the panic - /// messages to a crash report file while showing users a more friendly - /// "Oops, something went wrong!" message with a suggestion to send the - /// crash report file back to the developers. Panic messages should be used - /// to represent bugs, and the information provided back is context intended - /// for the developer, not the user. - /// - /// [panic hook]: https://doc.rust-lang.org/stable/std/panic/fn.set_hook.html - /// [`human-panic`]: https://docs.rs/human-panic + /// For more detail on expect message styles and the reasoning behind our + /// recommendation please refer to the section on ["Common Message + /// Styles"]() in the [`std::error`]() module docs. #[inline] #[track_caller] #[stable(feature = "result_expect", since = "1.4.0")] diff --git a/std/src/error.rs b/std/src/error.rs index 4fb94908c..84089075f 100644 --- a/std/src/error.rs +++ b/std/src/error.rs @@ -1,4 +1,135 @@ -//! Traits for working with Errors. +//! Interfaces for working with Errors. +//! +//! # Error Handling In Rust +//! +//! 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." The +//! components of the first system, the panic runtime and interfaces, are most +//! commonly used to represent bugs that have been detected in your program. The +//! components of the second system, `Result`, the error traits, and user +//! defined types, are used to represent anticipated runtime failure modes of +//! your program. +//! +//! ## The Panic Interfaces +//! +//! The following are the primary interfaces of the panic system and the +//! responsibilities they cover: +//! +//! * [`panic!`] and [`panic_any`] (Constructing, Propagated automatically) +//! * [`PanicInfo`] (Reporting) +//! * [`set_hook`], [`take_hook`], and [`#[panic_handler]`] (Reporting) +//! * [`catch_unwind`] and [`resume_unwind`] (Discarding, Propagating) +//! +//! The following are the primary interfaces of the error system and the +//! responsibilities they cover: +//! +//! * [`Result`] (Propagating, Reacting) +//! * The [`Error`] trait (Reporting) +//! * User defined types (Constructing / Representing) +//! * `match` and [`downcast`] (Reacting) +//! * The propagation operator (`?`) (Propagating) +//! * The partially stable [`Try`] traits (Propagating, Constructing) +//! * [`Termination`] (Reporting) +//! +//! ## Converting Errors into Panics +//! +//! The panic and error systems are not entirely distinct. Often times errors +//! that are anticipated runtime failures in an API might instead represent bugs +//! to a caller. For these situations the standard library provides APIs for +//! constructing panics with an `Error` as it's source. +//! +//! * `Result::unwrap` +//! * `Result::expect` +//! +//! TODO: how do I bridge these two sections? +//! +//! * unwrap is used in prototyping +//! * expect is used in !prototyping (????) +//! +//! # Common Message Styles +//! +//! There are two common styles for how people word `expect` messages. Using +//! the message to present information to users encountering a panic +//! ("expect as error message") or using the message to present information +//! to developers debugging the panic ("expect as precondition"). +//! +//! In the former case the expect message is used to describe the error that +//! has occurred which is considered a bug. Consider the following example: +//! +//! ```should_panic +//! // Read environment variable, panic if it is not present +//! let path = std::env::var("IMPORTANT_PATH").unwrap(); +//! ``` +//! +//! In the "expect as error message" style we would use expect to describe +//! that the environment variable was not set when it should have been: +//! +//! ```should_panic +//! let path = std::env::var("IMPORTANT_PATH") +//! .expect("env variable `IMPORTANT_PATH` is not set"); +//! ``` +//! +//! In the "expect as precondition" style, we would instead describe the +//! reason we _expect_ the `Result` should be `Ok`. With this style we would +//! prefer to write: +//! +//! ```should_panic +//! let path = std::env::var("IMPORTANT_PATH") +//! .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); +//! ``` +//! +//! The "expect as error message" style does not work as well with the +//! default output of the std panic hooks, and often ends up repeating +//! information that is already communicated by the source error being +//! unwrapped: +//! +//! ```text +//! thread 'main' panicked at 'env variable `IMPORTANT_PATH` is not set: NotPresent', src/main.rs:4:6 +//! ``` +//! +//! In this example we end up mentioning that an env variable is not set, +//! followed by our source message that says the env is not present, the +//! only additional information we're communicating is the name of the +//! environment variable being checked. +//! +//! The "expect as precondition" style instead focuses on source code +//! readability, making it easier to understand what must have gone wrong in +//! situations where panics are being used to represent bugs exclusively. +//! Also, by framing our expect in terms of what "SHOULD" have happened to +//! prevent the source error, we end up introducing new information that is +//! independent from our source error. +//! +//! ```text +//! thread 'main' panicked at 'env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent', src/main.rs:4:6 +//! ``` +//! +//! In this example we are communicating not only the name of the +//! environment variable that should have been set, but also an explanation +//! for why it should have been set, and we let the source error display as +//! a clear contradiction to our expectation. +//! +//! For programs where panics may be user facing, either style works best +//! when paired with a custom [panic hook] like the one provided by the CLI +//! working group library, [`human-panic`]. This panic hook dumps the panic +//! messages to a crash report file while showing users a more friendly +//! "Oops, something went wrong!" message with a suggestion to send the +//! crash report file back to the developers. Panic messages should be used +//! to represent bugs, and the information provided back is context intended +//! for the developer, not the user. +//! +//! [panic hook]: crate::panic::set_hook +//! [`set_hook`]: crate::panic::set_hook +//! [`take_hook`]: crate::panic::take_hook +//! [`PanicInfo`]: crate::panic::PanicInfo +//! [`panic_any`]: crate::panic::panic_any +//! [`#[panic_handler]`]: https://doc.rust-lang.org/nomicon/panic-handler.html +//! [`catch_unwind`]: crate::panic::catch_unwind +//! [`resume_unwind`]: crate::panic::resume_unwind +//! [`Termination`]: crate::process::Termination +//! [`Try`]: crate::ops::Try +//! [`downcast`]: crate::error::Error +//! [`human-panic`]: https://docs.rs/human-panic #![stable(feature = "rust1", since = "1.0.0")] From ff6752ce7396492d663cdeae1ec6b81541bd6ba6 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 24 May 2022 22:51:54 +0000 Subject: [PATCH 09/12] explained unwrap vs expect --- std/src/error.rs | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/std/src/error.rs b/std/src/error.rs index 84089075f..c5782d452 100644 --- a/std/src/error.rs +++ b/std/src/error.rs @@ -42,10 +42,18 @@ //! * `Result::unwrap` //! * `Result::expect` //! -//! TODO: how do I bridge these two sections? +//! These functions are equivalent, they either return the inner value if the +//! `Result` is `Ok` or panic if the `Result` is `Err` printing the inner error +//! as the source. The only difference between them is that with `expect` you +//! provide a panic error message to be printed alongside the source, whereas +//! `unwrap` has a default message indicating only that you unwraped an `Err`. //! -//! * unwrap is used in prototyping -//! * expect is used in !prototyping (????) +//! Of the two, `expect` is generally preferred since its `msg` field allows you +//! to convey your intent and assumptions which makes tracking down the source +//! of a panic easier. `unwrap` on the other hand can still be a good fit in +//! situations where you can trivially show that a piece of code will never +//! panick, such as `"127.0.0.1".parse::().unwrap()` or early +//! prototyping. //! //! # Common Message Styles //! @@ -109,14 +117,10 @@ //! for why it should have been set, and we let the source error display as //! a clear contradiction to our expectation. //! -//! For programs where panics may be user facing, either style works best -//! when paired with a custom [panic hook] like the one provided by the CLI -//! working group library, [`human-panic`]. This panic hook dumps the panic -//! messages to a crash report file while showing users a more friendly -//! "Oops, something went wrong!" message with a suggestion to send the -//! crash report file back to the developers. Panic messages should be used -//! to represent bugs, and the information provided back is context intended -//! for the developer, not the user. +//! **Hint**: If you're having trouble remembering how to phrase +//! expect-as-precondition style error messages remember to focus on the word +//! "should" as in "env variable should be set by blah" or "the given binary +//! should be available and executable by the current user". //! //! [panic hook]: crate::panic::set_hook //! [`set_hook`]: crate::panic::set_hook @@ -129,7 +133,6 @@ //! [`Termination`]: crate::process::Termination //! [`Try`]: crate::ops::Try //! [`downcast`]: crate::error::Error -//! [`human-panic`]: https://docs.rs/human-panic #![stable(feature = "rust1", since = "1.0.0")] From dde7254cb84a84e4f124eb0730f7d7e014cccc2a Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 25 May 2022 10:46:56 -0700 Subject: [PATCH 10/12] fix links --- std/src/error.rs | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/std/src/error.rs b/std/src/error.rs index c5782d452..41a632cda 100644 --- a/std/src/error.rs +++ b/std/src/error.rs @@ -18,7 +18,7 @@ //! //! * [`panic!`] and [`panic_any`] (Constructing, Propagated automatically) //! * [`PanicInfo`] (Reporting) -//! * [`set_hook`], [`take_hook`], and [`#[panic_handler]`] (Reporting) +//! * [`set_hook`], [`take_hook`], and [`#[panic_handler]`][panic-handler] (Reporting) //! * [`catch_unwind`] and [`resume_unwind`] (Discarding, Propagating) //! //! The following are the primary interfaces of the error system and the @@ -27,8 +27,8 @@ //! * [`Result`] (Propagating, Reacting) //! * The [`Error`] trait (Reporting) //! * User defined types (Constructing / Representing) -//! * `match` and [`downcast`] (Reacting) -//! * The propagation operator (`?`) (Propagating) +//! * [`match`] and [`downcast`] (Reacting) +//! * The question mark operator ([`?`]) (Propagating) //! * The partially stable [`Try`] traits (Propagating, Constructing) //! * [`Termination`] (Reporting) //! @@ -39,8 +39,8 @@ //! to a caller. For these situations the standard library provides APIs for //! constructing panics with an `Error` as it's source. //! -//! * `Result::unwrap` -//! * `Result::expect` +//! * [`Result::unwrap`] +//! * [`Result::expect`] //! //! These functions are equivalent, they either return the inner value if the //! `Result` is `Ok` or panic if the `Result` is `Err` printing the inner error @@ -122,17 +122,19 @@ //! "should" as in "env variable should be set by blah" or "the given binary //! should be available and executable by the current user". //! -//! [panic hook]: crate::panic::set_hook -//! [`set_hook`]: crate::panic::set_hook -//! [`take_hook`]: crate::panic::take_hook -//! [`PanicInfo`]: crate::panic::PanicInfo //! [`panic_any`]: crate::panic::panic_any -//! [`#[panic_handler]`]: https://doc.rust-lang.org/nomicon/panic-handler.html +//! [`PanicInfo`]: crate::panic::PanicInfo //! [`catch_unwind`]: crate::panic::catch_unwind //! [`resume_unwind`]: crate::panic::resume_unwind +//! [`downcast`]: crate::error::Error //! [`Termination`]: crate::process::Termination //! [`Try`]: crate::ops::Try -//! [`downcast`]: crate::error::Error +//! [panic hook]: crate::panic::set_hook +//! [`set_hook`]: crate::panic::set_hook +//! [`take_hook`]: crate::panic::take_hook +//! [panic-handler]: +//! [`match`]: ../../std/keyword.match.html +//! [`?`]: ../../std/result/index.html#the-question-mark-operator- #![stable(feature = "rust1", since = "1.0.0")] From db7abf6c48e4ddc6a6e001240eb7e60f6c3a441d Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 25 May 2022 11:37:39 -0700 Subject: [PATCH 11/12] update option and result references to expect message docs --- core/src/option.rs | 20 ++++++++++++++++++-- core/src/result.rs | 12 +++++++++--- 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/core/src/option.rs b/core/src/option.rs index f280c321c..77619d61d 100644 --- a/core/src/option.rs +++ b/core/src/option.rs @@ -709,8 +709,24 @@ impl Option { /// x.expect("fruits are healthy"); // panics with `fruits are healthy` /// ``` /// - /// **Note**: Please refer to the documentation on [`Result::expect`] for further information - /// on common message styles. + /// # Recommended Message Style + /// + /// We recommend that `expect` messages are used to describe the reason you + /// _expect_ the `Option` should be `Some`. + /// + /// ```should_panic + /// let item = slice.get(0) + /// .expect("slice should not be empty"); + /// ``` + /// + /// **Hint**: If you're having trouble remembering how to phrase expect + /// error messages remember to focus on the word "should" as in "env + /// variable should be set by blah" or "the given binary should be available + /// and executable by the current user". + /// + /// For more detail on expect message styles and the reasoning behind our + /// recommendation please refer to the section on ["Common Message + /// Styles"](../../std/error/index.html#common-message-styles) in the [`std::error`](../../std/error/index.html) module docs. #[inline] #[track_caller] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/core/src/result.rs b/core/src/result.rs index 342acea29..6f204df99 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -1034,9 +1034,15 @@ impl Result { /// .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); /// ``` /// - /// For more detail on expect message styles and the reasoning behind our - /// recommendation please refer to the section on ["Common Message - /// Styles"]() in the [`std::error`]() module docs. + /// **Hint**: If you're having trouble remembering how to phrase expect + /// error messages remember to focus on the word "should" as in "env + /// variable should be set by blah" or "the given binary should be available + /// and executable by the current user". + /// + /// For more detail on expect message styles and the reasoning behind our recommendation please + /// refer to the section on ["Common Message + /// Styles"](../../std/error/index.html#common-message-styles) in the + /// [`std::error`](../../std/error/index.html) module docs. #[inline] #[track_caller] #[stable(feature = "result_expect", since = "1.4.0")] From 1de8606cf0776615d426eac80511000b8e52b9aa Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 25 May 2022 12:20:48 -0700 Subject: [PATCH 12/12] fix broken doctest --- core/src/option.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/core/src/option.rs b/core/src/option.rs index 77619d61d..cfa77f39f 100644 --- a/core/src/option.rs +++ b/core/src/option.rs @@ -715,6 +715,7 @@ impl Option { /// _expect_ the `Option` should be `Some`. /// /// ```should_panic + /// # let slice: &[u8] = &[]; /// let item = slice.get(0) /// .expect("slice should not be empty"); /// ```