From 720e987ac0a2123ab00046af0a91c57258fde9aa Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 25 May 2022 11:37:39 -0700 Subject: [PATCH] update option and result references to expect message docs --- library/core/src/option.rs | 20 ++++++++++++++++++-- library/core/src/result.rs | 12 +++++++++--- 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index f280c321c9c..77619d61d9f 100644 --- a/library/core/src/option.rs +++ b/library/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/library/core/src/result.rs b/library/core/src/result.rs index 342acea29dc..6f204df9998 100644 --- a/library/core/src/result.rs +++ b/library/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")]