From d2495facb14b6e79b70d98847fd8dfd6f0023e70 Mon Sep 17 00:00:00 2001
From: Lukas Bergdoll <lukas.bergdoll@gmail.com>
Date: Thu, 29 Feb 2024 09:52:02 +0100
Subject: [PATCH] Drop link to matches macro and link matches macro to
 assert_matches.

---
 library/core/src/macros/mod.rs | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs
index 949b07dfb77..62ff3181ef8 100644
--- a/library/core/src/macros/mod.rs
+++ b/library/core/src/macros/mod.rs
@@ -118,7 +118,7 @@ macro_rules! assert_ne {
 /// the debug representation, of the actual value shape that did not meet expectation. In contrast
 /// using [`assert!`] will only print that the expectation was not met, but not why.
 ///
-/// The pattern syntax is exactly the same as found in a match arm and the [`matches!`] macro. The
+/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
 /// optional if guard can be used to add additional checks that must be true for the matched value,
 /// otherwise this macro will panic.
 ///
@@ -385,7 +385,7 @@ macro_rules! debug_assert_ne {
 /// print the debug representation, of the actual value shape that did not meet expectation. In
 /// contrast using [`debug_assert!`] will only print that the expectation was not met, but not why.
 ///
-/// The pattern syntax is exactly the same as found in a match arm and the [`matches!`] macro. The
+/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The
 /// optional if guard can be used to add additional checks that must be true for the matched value,
 /// otherwise this macro will panic.
 ///
@@ -430,10 +430,15 @@ macro_rules! debug_assert_ne {
     }
 }
 
-/// 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`
-/// and a guard expression that has access to names bound by the pattern.
+/// The pattern syntax is exactly the same as found in a match arm. The optional if guard can be
+/// 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
 ///