diff --git a/compiler/rustc_lint/src/lints.rs b/compiler/rustc_lint/src/lints.rs
index 1632ca960a4f..216933b4377f 100644
--- a/compiler/rustc_lint/src/lints.rs
+++ b/compiler/rustc_lint/src/lints.rs
@@ -325,7 +325,7 @@ pub struct BuiltinTypeAliasGenericBounds<'a, 'b> {
 
 #[derive(LintDiagnostic)]
 #[diag(lint_macro_expr_fragment_specifier_2024_migration)]
-pub struct MacroExprFragment2023 {
+pub struct MacroExprFragment2024 {
     #[suggestion(code = "expr_2021", applicability = "machine-applicable")]
     pub suggestion: Span,
 }
diff --git a/compiler/rustc_lint/src/macro_expr_fragment_specifier_2024_migration.rs b/compiler/rustc_lint/src/macro_expr_fragment_specifier_2024_migration.rs
index b84568d875e9..cea15f19403e 100644
--- a/compiler/rustc_lint/src/macro_expr_fragment_specifier_2024_migration.rs
+++ b/compiler/rustc_lint/src/macro_expr_fragment_specifier_2024_migration.rs
@@ -12,14 +12,38 @@ use rustc_session::lint::FutureIncompatibilityReason;
 use rustc_span::edition::Edition;
 use rustc_span::sym;
 
-use crate::lints::MacroExprFragment2023;
+use crate::lints::MacroExprFragment2024;
 use crate::EarlyLintPass;
 
 declare_lint! {
+    /// FIXME: better docs for the 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.
+    ///
+    /// FIXME: change this: You can manually change the identifiers from `expr` to `expr2021`,
+    ///  or use a [raw identifier], for example `r#gen`, to transition to a new edition.
+    ///
+    /// 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 (which is
+    /// to use a raw identifier). This provides a completely automated way to
+    /// update old code for a new edition.
+    ///
+    /// [editions]: https://doc.rust-lang.org/edition-guide/
+    /// [raw identifier]: https://doc.rust-lang.org/reference/identifiers.html
+    /// [`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html
     pub EDITION_2024_EXPR_FRAGMENT_SPECIFIER,
     Allow,
     "The `expr` fragment specifier will accept more expressions in the 2024 edition. \
-    To keep the existing before, use the `expr_2021` fragment specifier.",
+    To keep the existing behavior, use the `expr_2021` fragment specifier.",
     @future_incompatible = FutureIncompatibleInfo {
         reason: FutureIncompatibilityReason::EditionSemanticsChange(Edition::Edition2024),
         reference: "issue #123742 <https://github.com/rust-lang/rust/issues/123742>",
@@ -30,11 +54,9 @@ declare_lint_pass!(Expr2024 => [EDITION_2024_EXPR_FRAGMENT_SPECIFIER,]);
 
 impl Expr2024 {
     fn check_tokens(&mut self, cx: &crate::EarlyContext<'_>, tokens: &TokenStream) {
-        // Check if the preceding token is `$`, because we want to allow `$async`, etc.
         let mut prev_dollar = false;
         for tt in tokens.trees() {
             match tt {
-                // Only report non-raw idents.
                 TokenTree::Token(token, _) => {
                     if token.kind == TokenKind::Dollar {
                         prev_dollar = true;
@@ -71,7 +93,7 @@ impl Expr2024 {
         cx.builder.emit_span_lint(
             &EDITION_2024_EXPR_FRAGMENT_SPECIFIER,
             token.span.into(),
-            MacroExprFragment2023 { suggestion: token.span },
+            MacroExprFragment2024 { suggestion: token.span },
         );
     }
 }