Skip to content

Commit b2c451d

Browse files
GuillaumeGomezGuillaumeGomez
committed
Improve mistyped docblock attribute warning messages
1 parent f461118 commit b2c451d

File tree

5 files changed

+85
-89
lines changed

5 files changed

+85
-89
lines changed

‎src/librustdoc/html/markdown.rs

+27-31
Original file line numberDiff line numberDiff line change
@@ -1298,37 +1298,31 @@ impl LangString {
12981298
}
12991299
LangStringToken::LangToken(x) if extra.is_some() => {
13001300
let s = x.to_lowercase();
1301-
if let Some((flag, help)) = match s.as_str() {
1302-
"compile-fail" | "compile_fail" | "compilefail" => Some((
1303-
"compile_fail",
1304-
"the code block will either not be tested if not marked as a rust \
1305-
one or won't fail if it compiles successfully",
1306-
)),
1307-
"should-panic" | "should_panic" | "shouldpanic" => Some((
1308-
"should_panic",
1309-
"the code block will either not be tested if not marked as a rust \
1310-
one or won't fail if it doesn't panic when running",
1311-
)),
1312-
"no-run" | "no_run" | "norun" => Some((
1313-
"no_run",
1314-
"the code block will either not be tested if not marked as a rust \
1315-
one or will be run (which you might not want)",
1316-
)),
1317-
"test-harness" | "test_harness" | "testharness" => Some((
1318-
"test_harness",
1319-
"the code block will either not be tested if not marked as a rust \
1320-
one or the code will be wrapped inside a main function",
1321-
)),
1301+
if let Some(help) = match s.as_str() {
1302+
"compile-fail" | "compile_fail" | "compilefail" => Some(
1303+
"use `compile_fail` to invert the results of this test, so that it \
1304+
passes if it cannot be compiled and fails if it can",
1305+
),
1306+
"should-panic" | "should_panic" | "shouldpanic" => Some(
1307+
"use `should_panic` to invert the results of this test, so that if \
1308+
passes if it panics and fails if it does not",
1309+
),
1310+
"no-run" | "no_run" | "norun" => Some(
1311+
"use `no_run` to compile, but not run, the code sample during \
1312+
testing",
1313+
),
1314+
"test-harness" | "test_harness" | "testharness" => Some(
1315+
"use `test_harness` to run functions marked `#[test]` instead of a \
1316+
potentially-implicit `main` function",
1317+
),
13221318
"standalone" | "standalone_crate" => {
13231319
if let Some(extra) = extra
13241320
&& extra.sp.at_least_rust_2024()
13251321
{
1326-
Some((
1327-
"standalone-crate",
1328-
"the code block will either not be tested if not marked as \
1329-
a rust one or the code will be run as part of the merged \
1330-
doctests if compatible",
1331-
))
1322+
Some(
1323+
"use `standalone-crate` to compile this code block \
1324+
separately",
1325+
)
13321326
} else {
13331327
None
13341328
}
@@ -1339,10 +1333,12 @@ impl LangString {
13391333
extra.error_invalid_codeblock_attr_with_help(
13401334
format!("unknown attribute `{x}`"),
13411335
|lint| {
1342-
lint.help(format!(
1343-
"there is an attribute with a similar name: `{flag}`"
1344-
))
1345-
.help(help);
1336+
lint.help(help).help(
1337+
"this code block may be skipped during testing, \
1338+
because unknown attributes are treated as markers for \
1339+
code samples written in other programming languages, \
1340+
unless it is also explicitly marked as `rust`",
1341+
);
13461342
},
13471343
);
13481344
}

‎tests/rustdoc-ui/doctest/check-attr-test.stderr

+24-24
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ error: unknown attribute `compile-fail`
88
9 | | /// ```
99
| |_______^
1010
|
11-
= help: there is an attribute with a similar name: `compile_fail`
12-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
11+
= 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
12+
= 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`
1313
note: the lint level is defined here
1414
--> $DIR/check-attr-test.rs:3:9
1515
|
@@ -26,8 +26,8 @@ error: unknown attribute `compilefail`
2626
9 | | /// ```
2727
| |_______^
2828
|
29-
= help: there is an attribute with a similar name: `compile_fail`
30-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
29+
= 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
30+
= 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`
3131

3232
error: unknown attribute `comPile_fail`
3333
--> $DIR/check-attr-test.rs:5:1
@@ -39,8 +39,8 @@ error: unknown attribute `comPile_fail`
3939
9 | | /// ```
4040
| |_______^
4141
|
42-
= help: there is an attribute with a similar name: `compile_fail`
43-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
42+
= 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
43+
= 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`
4444

4545
error: unknown attribute `should-panic`
4646
--> $DIR/check-attr-test.rs:12:1
@@ -52,8 +52,8 @@ error: unknown attribute `should-panic`
5252
16 | | /// ```
5353
| |_______^
5454
|
55-
= help: there is an attribute with a similar name: `should_panic`
56-
= 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
55+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
56+
= 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`
5757

5858
error: unknown attribute `shouldpanic`
5959
--> $DIR/check-attr-test.rs:12:1
@@ -65,8 +65,8 @@ error: unknown attribute `shouldpanic`
6565
16 | | /// ```
6666
| |_______^
6767
|
68-
= help: there is an attribute with a similar name: `should_panic`
69-
= 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
68+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
69+
= 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`
7070

7171
error: unknown attribute `shOuld_panic`
7272
--> $DIR/check-attr-test.rs:12:1
@@ -78,8 +78,8 @@ error: unknown attribute `shOuld_panic`
7878
16 | | /// ```
7979
| |_______^
8080
|
81-
= help: there is an attribute with a similar name: `should_panic`
82-
= 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
81+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
82+
= 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`
8383

8484
error: unknown attribute `no-run`
8585
--> $DIR/check-attr-test.rs:19:1
@@ -91,8 +91,8 @@ error: unknown attribute `no-run`
9191
23 | | /// ```
9292
| |_______^
9393
|
94-
= help: there is an attribute with a similar name: `no_run`
95-
= 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)
94+
= help: use `no_run` to compile, but not run, the code sample during testing
95+
= 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`
9696

9797
error: unknown attribute `norun`
9898
--> $DIR/check-attr-test.rs:19:1
@@ -104,8 +104,8 @@ error: unknown attribute `norun`
104104
23 | | /// ```
105105
| |_______^
106106
|
107-
= help: there is an attribute with a similar name: `no_run`
108-
= 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)
107+
= help: use `no_run` to compile, but not run, the code sample during testing
108+
= 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`
109109

110110
error: unknown attribute `nO_run`
111111
--> $DIR/check-attr-test.rs:19:1
@@ -117,8 +117,8 @@ error: unknown attribute `nO_run`
117117
23 | | /// ```
118118
| |_______^
119119
|
120-
= help: there is an attribute with a similar name: `no_run`
121-
= 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)
120+
= help: use `no_run` to compile, but not run, the code sample during testing
121+
= 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`
122122

123123
error: unknown attribute `test-harness`
124124
--> $DIR/check-attr-test.rs:26:1
@@ -130,8 +130,8 @@ error: unknown attribute `test-harness`
130130
30 | | /// ```
131131
| |_______^
132132
|
133-
= help: there is an attribute with a similar name: `test_harness`
134-
= 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
133+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
134+
= 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`
135135

136136
error: unknown attribute `testharness`
137137
--> $DIR/check-attr-test.rs:26:1
@@ -143,8 +143,8 @@ error: unknown attribute `testharness`
143143
30 | | /// ```
144144
| |_______^
145145
|
146-
= help: there is an attribute with a similar name: `test_harness`
147-
= 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
146+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
147+
= 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`
148148

149149
error: unknown attribute `tesT_harness`
150150
--> $DIR/check-attr-test.rs:26:1
@@ -156,8 +156,8 @@ error: unknown attribute `tesT_harness`
156156
30 | | /// ```
157157
| |_______^
158158
|
159-
= help: there is an attribute with a similar name: `test_harness`
160-
= 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
159+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
160+
= 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`
161161

162162
error: aborting due to 12 previous errors
163163

‎tests/rustdoc-ui/doctest/standalone-warning-2024.stderr

+4-4
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ error: unknown attribute `standalone`
1010
16 | | //! ```
1111
| |_______^
1212
|
13-
= help: there is an attribute with a similar name: `standalone-crate`
14-
= 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
13+
= help: use `standalone-crate` to compile this code block separately
14+
= 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`
1515
note: the lint level is defined here
1616
--> $DIR/standalone-warning-2024.rs:8:9
1717
|
@@ -31,8 +31,8 @@ error: unknown attribute `standalone_crate`
3131
16 | | //! ```
3232
| |_______^
3333
|
34-
= help: there is an attribute with a similar name: `standalone-crate`
35-
= 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
34+
= help: use `standalone-crate` to compile this code block separately
35+
= 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`
3636

3737
error: aborting due to 2 previous errors
3838

0 commit comments

Comments
 (0)