Rollup merge of #121732 - Voultapher:improve-assert_matches-documentation, r=cuviper

Improve assert_matches! documentation

This new documentation tries to limit the impact of the conceptual pitfall, that the if guard relaxes the constraint, when really it tightens it. This is achieved by changing the text and examples. The previous documentation also chose a rather weird and non-representative example for the if guard, that made it needlessly complicated to understand.

library/core/src/macros/mod.rs

@@ -112,16 +112,19 @@ macro_rules! assert_ne {
     };
 }
 
-/// Asserts that an expression matches any of the given patterns.
+/// Asserts that an expression matches the provided pattern.
 ///
-/// Like in a `match` expression, the pattern can be optionally followed by `if`
+/// This macro is generally preferable to `assert!(matches!(value, pattern))`, because it can print
-/// and a guard expression that has access to names bound by the pattern.
+/// the debug representation of the actual value shape that did not meet expectations. In contrast,
+/// using [`assert!`] will only print that expectations were not met, but not why.
 ///
-/// On panic, this macro will print the value of the expression with its
+/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
-/// debug representation.
+/// optional if guard can be used to add additional checks that must be true for the matched value,
+/// otherwise this macro will panic.
 ///
-/// Like [`assert!`], this macro has a second form, where a custom
+/// On panic, this macro will print the value of the expression with its debug representation.
-/// panic message can be provided.
+///
+/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided.
 ///
 /// # Examples
 ///
@@ -130,13 +133,20 @@ macro_rules! assert_ne {
 ///
 /// use std::assert_matches::assert_matches;
 ///
-/// let a = 1u32.checked_add(2);
+/// let a = Some(345);
-/// let b = 1u32.checked_sub(2);
+/// let b = Some(56);
 /// assert_matches!(a, Some(_));
-/// assert_matches!(b, None);
+/// assert_matches!(b, Some(_));
 ///
-/// let c = Ok("abc".to_string());
+/// assert_matches!(a, Some(345));
-/// assert_matches!(c, Ok(x) | Err(x) if x.len() < 100);
+/// assert_matches!(a, Some(345) | None);
+///
+/// // assert_matches!(a, None); // panics
+/// // assert_matches!(b, Some(345)); // panics
+/// // assert_matches!(b, Some(345) | None); // panics
+///
+/// assert_matches!(a, Some(x) if x > 100);
+/// // assert_matches!(a, Some(x) if x < 100); // panics
 /// ```
 #[unstable(feature = "assert_matches", issue = "82775")]
 #[allow_internal_unstable(panic_internals)]
@@ -369,21 +379,25 @@ macro_rules! debug_assert_ne {
     };
 }
 
-/// Asserts that an expression matches any of the given patterns.
+/// Asserts that an expression matches the provided pattern.
 ///
-/// Like in a `match` expression, the pattern can be optionally followed by `if`
+/// This macro is generally preferable to `debug_assert!(matches!(value, pattern))`, because it can
-/// and a guard expression that has access to names bound by the pattern.
+/// print the debug representation of the actual value shape that did not meet expectations. In
+/// contrast, using [`debug_assert!`] will only print that expectations were not met, but not why.
 ///
-/// On panic, this macro will print the value of the expression with its
+/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
-/// debug representation.
+/// optional if guard can be used to add additional checks that must be true for the matched value,
+/// otherwise this macro will panic.
 ///
-/// Unlike [`assert_matches!`], `debug_assert_matches!` statements are only
+/// On panic, this macro will print the value of the expression with its debug representation.
-/// enabled in non optimized builds by default. An optimized build will not
+///
-/// execute `debug_assert_matches!` statements unless `-C debug-assertions` is
+/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided.
-/// passed to the compiler. This makes `debug_assert_matches!` useful for
+///
-/// checks that are too expensive to be present in a release build but may be
+/// Unlike [`assert_matches!`], `debug_assert_matches!` statements are only enabled in non optimized
-/// helpful during development. The result of expanding `debug_assert_matches!`
+/// builds by default. An optimized build will not execute `debug_assert_matches!` statements unless
-/// is always type checked.
+/// `-C debug-assertions` is passed to the compiler. This makes `debug_assert_matches!` useful for
+/// checks that are too expensive to be present in a release build but may be helpful during
+/// development. The result of expanding `debug_assert_matches!` is always type checked.
 ///
 /// # Examples
 ///
@@ -392,13 +406,20 @@ macro_rules! debug_assert_ne {
 ///
 /// use std::assert_matches::debug_assert_matches;
 ///
-/// let a = 1u32.checked_add(2);
+/// let a = Some(345);
-/// let b = 1u32.checked_sub(2);
+/// let b = Some(56);
 /// debug_assert_matches!(a, Some(_));
-/// debug_assert_matches!(b, None);
+/// debug_assert_matches!(b, Some(_));
 ///
-/// let c = Ok("abc".to_string());
+/// debug_assert_matches!(a, Some(345));
-/// debug_assert_matches!(c, Ok(x) | Err(x) if x.len() < 100);
+/// debug_assert_matches!(a, Some(345) | None);
+///
+/// // debug_assert_matches!(a, None); // panics
+/// // debug_assert_matches!(b, Some(345)); // panics
+/// // debug_assert_matches!(b, Some(345) | None); // panics
+///
+/// debug_assert_matches!(a, Some(x) if x > 100);
+/// // debug_assert_matches!(a, Some(x) if x < 100); // panics
 /// ```
 #[unstable(feature = "assert_matches", issue = "82775")]
 #[allow_internal_unstable(assert_matches)]
@@ -409,10 +430,15 @@ pub macro debug_assert_matches($($arg:tt)*) {
     }
 }
 
-/// Returns whether the given expression matches any of the given patterns.
+/// Returns whether the given expression matches the provided pattern.
 ///
-/// Like in a `match` expression, the pattern can be optionally followed by `if`
+/// The pattern syntax is exactly the same as found in a match arm. The optional if guard can be
-/// and a guard expression that has access to names bound by the pattern.
+/// used to add additional checks that must be true for the matched value, otherwise this macro will
+/// return `false`.
+///
+/// When testing that a value matches a pattern, it's generally preferable to use
+/// [`assert_matches!`] as it will print the debug representation of the value if the assertion
+/// fails.
 ///
 /// # Examples
 ///