Improve mistyped docblock attribute warning messages

5 files changed, 85 insertions, 89 deletions

diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs
index c487138152d..e1a8dc6e50c 100644
--- a/src/librustdoc/html/markdown.rs
+++ b/src/librustdoc/html/markdown.rs
@@ -1298,37 +1298,31 @@ impl LangString {
                     }
                     LangStringToken::LangToken(x) if extra.is_some() => {
                         let s = x.to_lowercase();
-                        if let Some((flag, help)) = match s.as_str() {
-                            "compile-fail" | "compile_fail" | "compilefail" => Some((
-                                "compile_fail",
-                                "the code block will either not be tested if not marked as a rust \
-                                 one or won't fail if it compiles successfully",
-                            )),
-                            "should-panic" | "should_panic" | "shouldpanic" => Some((
-                                "should_panic",
-                                "the code block will either not be tested if not marked as a rust \
-                                 one or won't fail if it doesn't panic when running",
-                            )),
-                            "no-run" | "no_run" | "norun" => Some((
-                                "no_run",
-                                "the code block will either not be tested if not marked as a rust \
-                                 one or will be run (which you might not want)",
-                            )),
-                            "test-harness" | "test_harness" | "testharness" => Some((
-                                "test_harness",
-                                "the code block will either not be tested if not marked as a rust \
-                                 one or the code will be wrapped inside a main function",
-                            )),
+                        if let Some(help) = match s.as_str() {
+                            "compile-fail" | "compile_fail" | "compilefail" => Some(
+                                "use `compile_fail` to invert the results of this test, so that it \
+                                passes if it cannot be compiled and fails if it can",
+                            ),
+                            "should-panic" | "should_panic" | "shouldpanic" => Some(
+                                "use `should_panic` to invert the results of this test, so that if \
+                                passes if it panics and fails if it does not",
+                            ),
+                            "no-run" | "no_run" | "norun" => Some(
+                                "use `no_run` to compile, but not run, the code sample during \
+                                testing",
+                            ),
+                            "test-harness" | "test_harness" | "testharness" => Some(
+                                "use `test_harness` to run functions marked `#[test]` instead of a \
+                                potentially-implicit `main` function",
+                            ),
                             "standalone" | "standalone_crate" => {
                                 if let Some(extra) = extra
                                     && extra.sp.at_least_rust_2024()
                                 {
-                                    Some((
-                                        "standalone-crate",
-                                        "the code block will either not be tested if not marked as \
-                                         a rust one or the code will be run as part of the merged \
-                                         doctests if compatible",
-                                    ))
+                                    Some(
+                                        "use `standalone-crate` to compile this code block \
+                                        separately",
+                                    )
                                 } else {
                                     None
                                 }
@@ -1339,10 +1333,12 @@ impl LangString {
                                 extra.error_invalid_codeblock_attr_with_help(
                                     format!("unknown attribute `{x}`"),
                                     |lint| {
-                                        lint.help(format!(
-                                            "there is an attribute with a similar name: `{flag}`"
-                                        ))
-                                        .help(help);
+                                        lint.help(help).help(
+                                            "this code block may be skipped during testing, \
+                                            because unknown attributes are treated as markers for \
+                                            code samples written in other programming languages, \
+                                            unless it is also explicitly marked as `rust`",
+                                        );
                                     },
                                 );
                             }
diff --git a/tests/rustdoc-ui/doctest/check-attr-test.stderr b/tests/rustdoc-ui/doctest/check-attr-test.stderr
index 10f763a6f9d..257136d1633 100644
--- a/tests/rustdoc-ui/doctest/check-attr-test.stderr
+++ b/tests/rustdoc-ui/doctest/check-attr-test.stderr
@@ -8,8 +8,8 @@ error: unknown attribute `compile-fail`
 9 | | /// ```
   | |_______^
   |
-  = help: there is an attribute with a similar name: `compile_fail`
-  = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+  = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+  = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 note: the lint level is defined here
  --> $DIR/check-attr-test.rs:3:9
   |
@@ -26,8 +26,8 @@ error: unknown attribute `compilefail`
 9 | | /// ```
   | |_______^
   |
-  = help: there is an attribute with a similar name: `compile_fail`
-  = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+  = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+  = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `comPile_fail`
  --> $DIR/check-attr-test.rs:5:1
@@ -39,8 +39,8 @@ error: unknown attribute `comPile_fail`
 9 | | /// ```
   | |_______^
   |
-  = help: there is an attribute with a similar name: `compile_fail`
-  = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+  = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+  = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `should-panic`
   --> $DIR/check-attr-test.rs:12:1
@@ -52,8 +52,8 @@ error: unknown attribute `should-panic`
 16 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `shouldpanic`
   --> $DIR/check-attr-test.rs:12:1
@@ -65,8 +65,8 @@ error: unknown attribute `shouldpanic`
 16 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `shOuld_panic`
   --> $DIR/check-attr-test.rs:12:1
@@ -78,8 +78,8 @@ error: unknown attribute `shOuld_panic`
 16 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `no-run`
   --> $DIR/check-attr-test.rs:19:1
@@ -91,8 +91,8 @@ error: unknown attribute `no-run`
 23 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `norun`
   --> $DIR/check-attr-test.rs:19:1
@@ -104,8 +104,8 @@ error: unknown attribute `norun`
 23 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `nO_run`
   --> $DIR/check-attr-test.rs:19:1
@@ -117,8 +117,8 @@ error: unknown attribute `nO_run`
 23 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `test-harness`
   --> $DIR/check-attr-test.rs:26:1
@@ -130,8 +130,8 @@ error: unknown attribute `test-harness`
 30 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `testharness`
   --> $DIR/check-attr-test.rs:26:1
@@ -143,8 +143,8 @@ error: unknown attribute `testharness`
 30 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `tesT_harness`
   --> $DIR/check-attr-test.rs:26:1
@@ -156,8 +156,8 @@ error: unknown attribute `tesT_harness`
 30 | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: aborting due to 12 previous errors
 
diff --git a/tests/rustdoc-ui/doctest/standalone-warning-2024.stderr b/tests/rustdoc-ui/doctest/standalone-warning-2024.stderr
index ec9d17bb073..ef2e2364319 100644
--- a/tests/rustdoc-ui/doctest/standalone-warning-2024.stderr
+++ b/tests/rustdoc-ui/doctest/standalone-warning-2024.stderr
@@ -10,8 +10,8 @@ error: unknown attribute `standalone`
 16 | | //! ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `standalone-crate`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be run as part of the merged doctests if compatible
+   = help: use `standalone-crate` to compile this code block separately
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 note: the lint level is defined here
   --> $DIR/standalone-warning-2024.rs:8:9
    |
@@ -31,8 +31,8 @@ error: unknown attribute `standalone_crate`
 16 | | //! ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `standalone-crate`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be run as part of the merged doctests if compatible
+   = help: use `standalone-crate` to compile this code block separately
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: aborting due to 2 previous errors
 
diff --git a/tests/rustdoc-ui/lints/check-attr.stderr b/tests/rustdoc-ui/lints/check-attr.stderr
index d640125ab51..e23806e0bab 100644
--- a/tests/rustdoc-ui/lints/check-attr.stderr
+++ b/tests/rustdoc-ui/lints/check-attr.stderr
@@ -10,8 +10,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `compile_fail`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+   = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 note: the lint level is defined here
   --> $DIR/check-attr.rs:1:9
    |
@@ -30,8 +30,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `compile_fail`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+   = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `comPile_fail`
   --> $DIR/check-attr.rs:3:1
@@ -45,8 +45,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `compile_fail`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
+   = help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `should-panic`
   --> $DIR/check-attr.rs:13:1
@@ -60,8 +60,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `shouldpanic`
   --> $DIR/check-attr.rs:13:1
@@ -75,8 +75,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `sHould_panic`
   --> $DIR/check-attr.rs:13:1
@@ -90,8 +90,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `no-run`
   --> $DIR/check-attr.rs:23:1
@@ -105,8 +105,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `norun`
   --> $DIR/check-attr.rs:23:1
@@ -120,8 +120,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `no_Run`
   --> $DIR/check-attr.rs:23:1
@@ -135,8 +135,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `no_run`
-   = help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
+   = help: use `no_run` to compile, but not run, the code sample during testing
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `test-harness`
   --> $DIR/check-attr.rs:33:1
@@ -150,8 +150,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `testharness`
   --> $DIR/check-attr.rs:33:1
@@ -165,8 +165,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `teSt_harness`
   --> $DIR/check-attr.rs:33:1
@@ -180,8 +180,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: unknown attribute `rust2018`
   --> $DIR/check-attr.rs:43:1
@@ -222,8 +222,8 @@ LL | | /// boo
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `should_panic`
-   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
+   = help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: aborting due to 15 previous errors
 
diff --git a/tests/rustdoc-ui/lints/check-fail.stderr b/tests/rustdoc-ui/lints/check-fail.stderr
index 99b01bac598..2eb9496e5dc 100644
--- a/tests/rustdoc-ui/lints/check-fail.stderr
+++ b/tests/rustdoc-ui/lints/check-fail.stderr
@@ -31,8 +31,8 @@ LL | | //! let x = 12;
 LL | | //! ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 note: the lint level is defined here
   --> $DIR/check-fail.rs:6:9
    |
@@ -51,8 +51,8 @@ LL | | /// let x = 12;
 LL | | /// ```
    | |_______^
    |
-   = help: there is an attribute with a similar name: `test_harness`
-   = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
+   = help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
+   = help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
 
 error: aborting due to 4 previous errors