Add back missing help for ignore blocks

This also gives a better error message when a span is missing.

6 files changed, 40 insertions, 34 deletions

diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
index 7088e60aa07..46c4a8a41ac 100644
--- a/src/doc/rustdoc/src/lints.md
+++ b/src/doc/rustdoc/src/lints.md
@@ -328,7 +328,7 @@ warning: Rust code block is empty
 --> src/lib.rs:8:5
 |
 8 | /// ```rust
-|     ^^^^^^^
+|       ^^^^^^^
 ```
 
 ## bare_urls
diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs
index 293941391c8..4cc16de6808 100644
--- a/src/librustdoc/passes/check_code_block_syntax.rs
+++ b/src/librustdoc/passes/check_code_block_syntax.rs
@@ -61,7 +61,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
         };
 
         let hir_id = self.cx.tcx.hir().local_def_id_to_hir_id(local_id);
-        let suggest_using_text = code_block.syntax.is_none() && code_block.is_fenced;
+        let empty_block = code_block.syntax.is_none() && code_block.is_fenced;
         let is_ignore = code_block.is_ignore;
 
         // The span and whether it is precise or not.
@@ -78,40 +78,38 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
         // lambda that will use the lint to start a new diagnostic and add
         // a suggestion to it when needed.
         let diag_builder = |lint: LintDiagnosticBuilder<'_>| {
-            let mut diag = if precise_span {
-                let msg = if buffer.has_errors {
-                    "could not parse code block as Rust code"
-                } else {
-                    "Rust code block is empty"
-                };
-
-                let mut diag = lint.build(msg);
-
-                if suggest_using_text {
-                    let extended_msg = if is_ignore {
-                        "`ignore` code blocks require valid Rust code for syntax highlighting. \
-                         Mark blocks that do not contain Rust code as text"
-                    } else {
-                        "mark blocks that do not contain Rust code as text"
-                    };
+            let explanation = if is_ignore {
+                "`ignore` code blocks require valid Rust code for syntax highlighting; \
+                    mark blocks that do not contain Rust code as text"
+            } else {
+                "mark blocks that do not contain Rust code as text"
+            };
+            let msg = if buffer.has_errors {
+                "could not parse code block as Rust code"
+            } else {
+                "Rust code block is empty"
+            };
+            let mut diag = lint.build(msg);
 
+            if precise_span {
+                if is_ignore {
+                    // giving an accurate suggestion is hard because `ignore` might not have come first in the list.
+                    // just give a `help` instead.
+                    diag.span_help(
+                        sp.from_inner(InnerSpan::new(0, 3)),
+                        &format!("{}: ```text", explanation),
+                    );
+                } else if empty_block {
                     diag.span_suggestion(
                         sp.from_inner(InnerSpan::new(0, 3)),
-                        extended_msg,
+                        explanation,
                         String::from("```text"),
                         Applicability::MachineApplicable,
                     );
                 }
-
-                diag
-            } else {
-                let mut diag = lint.build("doc comment contains an invalid Rust code block");
-                if suggest_using_text {
-                    diag.help("mark blocks that do not contain Rust code as text: ```text");
-                }
-
-                diag
-            };
+            } else if empty_block || is_ignore {
+                diag.help(&format!("{}: ```text", explanation));
+            }
 
             // FIXME(#67563): Provide more context for these errors by displaying the spans inline.
             for message in buffer.messages.iter() {
diff --git a/src/test/rustdoc-ui/ignore-block-help.rs b/src/test/rustdoc-ui/ignore-block-help.rs
index c22dddd11df..86f6a2868fb 100644
--- a/src/test/rustdoc-ui/ignore-block-help.rs
+++ b/src/test/rustdoc-ui/ignore-block-help.rs
@@ -3,5 +3,8 @@
 /// ```ignore (to-prevent-tidy-error)
 /// let heart = '❤️';
 /// ```
-//~^^^ WARN
+//~^^^ WARNING could not parse code block
+//~| NOTE on by default
+//~| NOTE character literal may only contain one codepoint
+//~| HELP `ignore` code blocks require valid Rust code
 pub struct X;
diff --git a/src/test/rustdoc-ui/ignore-block-help.stderr b/src/test/rustdoc-ui/ignore-block-help.stderr
index 313b22c4c7c..b809ece86e7 100644
--- a/src/test/rustdoc-ui/ignore-block-help.stderr
+++ b/src/test/rustdoc-ui/ignore-block-help.stderr
@@ -7,7 +7,12 @@ LL | | /// let heart = '❤️';
 LL | | /// ```
    | |_______^
    |
-   = note: `#[warn(invalid_rust_codeblock)]` on by default
+   = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default
+help: `ignore` code blocks require valid Rust code for syntax highlighting; mark blocks that do not contain Rust code as text: ```text
+  --> $DIR/ignore-block-help.rs:3:5
+   |
+LL | /// ```ignore (to-prevent-tidy-error)
+   |     ^^^
    = note: error from rustc: character literal may only contain one codepoint
 
 warning: 1 warning emitted
diff --git a/src/test/rustdoc-ui/invalid-syntax.rs b/src/test/rustdoc-ui/invalid-syntax.rs
index c395a8ef3d4..b503d1093fd 100644
--- a/src/test/rustdoc-ui/invalid-syntax.rs
+++ b/src/test/rustdoc-ui/invalid-syntax.rs
@@ -71,7 +71,7 @@ pub fn blargh() {}
 /// \_
 #[doc = "```"]
 pub fn crazy_attrs() {}
-//~^^^^ WARNING doc comment contains an invalid Rust code block
+//~^^^^ WARNING could not parse code block
 
 /// ```rust
 /// ```
diff --git a/src/test/rustdoc-ui/invalid-syntax.stderr b/src/test/rustdoc-ui/invalid-syntax.stderr
index 67e093f9de2..7fcb9a0e9a9 100644
--- a/src/test/rustdoc-ui/invalid-syntax.stderr
+++ b/src/test/rustdoc-ui/invalid-syntax.stderr
@@ -7,7 +7,7 @@ LL | | /// \__________pkt->size___________/          \_result->size_/ \__pkt->si
 LL | | /// ```
    | |_______^
    |
-   = note: `#[warn(invalid_rust_codeblock)]` on by default
+   = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default
    = note: error from rustc: unknown start of token: \
    = note: error from rustc: unknown start of token: \
    = note: error from rustc: unknown start of token: \
@@ -91,7 +91,7 @@ LL | | /// ```
    |
    = note: error from rustc: unknown start of token: \
 
-warning: doc comment contains an invalid Rust code block
+warning: could not parse code block as Rust code
   --> $DIR/invalid-syntax.rs:70:1
    |
 LL | / #[doc = "```"]