From 632fed891df4850e579b2c796de7e18b53d80daa Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 28 Sep 2024 01:32:09 +0200 Subject: [PATCH] Improve mistyped docblock attribute warning messages --- src/librustdoc/html/markdown.rs | 58 +++++++++---------- .../rustdoc-ui/doctest/check-attr-test.stderr | 48 +++++++-------- .../doctest/standalone-warning-2024.stderr | 8 +-- tests/rustdoc-ui/lints/check-attr.stderr | 52 ++++++++--------- tests/rustdoc-ui/lints/check-fail.stderr | 8 +-- 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 @@ fn parse( } 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 @@ fn parse( 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