fixup! Adds expr_2024 migration lit

Signed-off-by: Vincenzo Palazzo <[email protected]>

compiler/rustc_lint/src/macro_expr_fragment_specifier_2024_migration.rs

@@ -16,11 +16,12 @@ use crate::lints::MacroExprFragment2024;
 use crate::EarlyLintPass;
 
 declare_lint! {
-    /// The `edition_2024_expr_fragment_specifier` lint detects the use of `expr` fragments
-    /// during migration to the 2024 edition.
+    /// The `edition_2024_expr_fragment_specifier` lint detects the use of
+    /// `expr` fragments in macros during migration to the 2024 edition.
     ///
-    /// The `expr` fragment specifier will accept more expressions in the 2024 edition.
-    /// To maintain the current behavior, use the `expr_2021` fragment specifier.
+    /// The `expr` fragment specifier will accept more expressions in the 2024
+    /// edition. To maintain the behavior from the 2021 edition and earlier, use
+    /// the `expr_2021` fragment specifier.
     ///
     /// ### Example
     ///
@@ -41,21 +42,34 @@ declare_lint! {
     ///
     /// ### Explanation
     ///
-    /// Rust [editions] allow the language to evolve without breaking
-    /// backwards compatibility. This lint catches code that uses new keywords
-    /// that are added to the language that are used as identifiers (such as a
-    /// variable name, function name, etc.). If you switch the compiler to a
-    /// new edition without updating the code, then it will fail to compile if
-    /// you are using a new keyword as an identifier.
+    /// Rust [editions] allow the language to evolve without breaking backwards
+    /// compatibility. This lint catches code that uses [macro matcher fragment
+    /// specifiers] that have changed meaning in the 2024 edition. If you switch
+    /// to the new edition without updating the code, your macros may behave
+    /// differently.
     ///
-    /// This lint solves the problem automatically. It is "allow" by default
-    /// because the code is perfectly valid in older editions. The [`cargo
-    /// fix`] tool with the `--edition` flag will switch this lint to "warn"
-    /// and automatically apply the suggested fix from the compiler.
-    /// This provides a completely automated way to update old code for
-    /// a new edition.
+    /// In the 2024 edition, the `expr` fragment specifier `expr` will also
+    /// match `const { ... }` blocks. This means if a macro had a pattern that
+    /// matched `$e:expr` and another that matches `const { $e: expr }`, for
+    /// example, that under the 2024 edition the first pattern would match while
+    /// in the 2021 and earlier editions the second pattern would match. To keep
+    /// the old behavior, use the `expr_2021` fragment specifier.
+    ///
+    /// This lint detects macros whose behavior might change due to the changing
+    /// meaning of the `expr` fragment specifier. It is "allow" by default
+    /// because the code is perfectly valid in older editions. The [`cargo fix`]
+    /// tool with the `--edition` flag will switch this lint to "warn" and
+    /// automatically apply the suggested fix from the compiler. This provides a
+    /// completely automated way to update old code for a new edition.
+    ///
+    /// Using `cargo fix --edition` with this lint will ensure that your code
+    /// retains the same behavior. This may not be the desired, as macro authors
+    /// often will want their macros to use the latest grammar for matching
+    /// expressions. Be sure to carefully review changes introduced by this lint
+    /// to ensure the macros implement the desired behavior.
     ///
     /// [editions]: https://doc.rust-lang.org/edition-guide/
+    /// [macro matcher fragment specifiers]: https://doc.rust-lang.org/nightly/edition-guide/rust-2024/macro-fragment-specifiers.html
     /// [`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html
     pub EDITION_2024_EXPR_FRAGMENT_SPECIFIER,
     Allow,