Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit b2c451d

Browse files
GuillaumeGomezGuillaumeGomez
committedSep 27, 2024·
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

Lines changed: 27 additions & 31 deletions
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

Lines changed: 24 additions & 24 deletions
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

Lines changed: 4 additions & 4 deletions
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

‎tests/rustdoc-ui/lints/check-attr.stderr

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ LL | | /// boo
1010
LL | | /// ```
1111
| |_______^
1212
|
13-
= help: there is an attribute with a similar name: `compile_fail`
14-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
13+
= 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
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/check-attr.rs:1:9
1717
|
@@ -30,8 +30,8 @@ LL | | /// boo
3030
LL | | /// ```
3131
| |_______^
3232
|
33-
= help: there is an attribute with a similar name: `compile_fail`
34-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
33+
= 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
34+
= 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`
3535

3636
error: unknown attribute `comPile_fail`
3737
--> $DIR/check-attr.rs:3:1
@@ -45,8 +45,8 @@ LL | | /// boo
4545
LL | | /// ```
4646
| |_______^
4747
|
48-
= help: there is an attribute with a similar name: `compile_fail`
49-
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
48+
= 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
49+
= 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`
5050

5151
error: unknown attribute `should-panic`
5252
--> $DIR/check-attr.rs:13:1
@@ -60,8 +60,8 @@ LL | | /// boo
6060
LL | | /// ```
6161
| |_______^
6262
|
63-
= help: there is an attribute with a similar name: `should_panic`
64-
= 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
63+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
64+
= 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`
6565

6666
error: unknown attribute `shouldpanic`
6767
--> $DIR/check-attr.rs:13:1
@@ -75,8 +75,8 @@ LL | | /// boo
7575
LL | | /// ```
7676
| |_______^
7777
|
78-
= help: there is an attribute with a similar name: `should_panic`
79-
= 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
78+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
79+
= 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`
8080

8181
error: unknown attribute `sHould_panic`
8282
--> $DIR/check-attr.rs:13:1
@@ -90,8 +90,8 @@ LL | | /// boo
9090
LL | | /// ```
9191
| |_______^
9292
|
93-
= help: there is an attribute with a similar name: `should_panic`
94-
= 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
93+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
94+
= 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`
9595

9696
error: unknown attribute `no-run`
9797
--> $DIR/check-attr.rs:23:1
@@ -105,8 +105,8 @@ LL | | /// boo
105105
LL | | /// ```
106106
| |_______^
107107
|
108-
= help: there is an attribute with a similar name: `no_run`
109-
= 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)
108+
= help: use `no_run` to compile, but not run, the code sample during testing
109+
= 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`
110110

111111
error: unknown attribute `norun`
112112
--> $DIR/check-attr.rs:23:1
@@ -120,8 +120,8 @@ LL | | /// boo
120120
LL | | /// ```
121121
| |_______^
122122
|
123-
= help: there is an attribute with a similar name: `no_run`
124-
= 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)
123+
= help: use `no_run` to compile, but not run, the code sample during testing
124+
= 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`
125125

126126
error: unknown attribute `no_Run`
127127
--> $DIR/check-attr.rs:23:1
@@ -135,8 +135,8 @@ LL | | /// boo
135135
LL | | /// ```
136136
| |_______^
137137
|
138-
= help: there is an attribute with a similar name: `no_run`
139-
= 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)
138+
= help: use `no_run` to compile, but not run, the code sample during testing
139+
= 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`
140140

141141
error: unknown attribute `test-harness`
142142
--> $DIR/check-attr.rs:33:1
@@ -150,8 +150,8 @@ LL | | /// boo
150150
LL | | /// ```
151151
| |_______^
152152
|
153-
= help: there is an attribute with a similar name: `test_harness`
154-
= 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
153+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
154+
= 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`
155155

156156
error: unknown attribute `testharness`
157157
--> $DIR/check-attr.rs:33:1
@@ -165,8 +165,8 @@ LL | | /// boo
165165
LL | | /// ```
166166
| |_______^
167167
|
168-
= help: there is an attribute with a similar name: `test_harness`
169-
= 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
168+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
169+
= 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`
170170

171171
error: unknown attribute `teSt_harness`
172172
--> $DIR/check-attr.rs:33:1
@@ -180,8 +180,8 @@ LL | | /// boo
180180
LL | | /// ```
181181
| |_______^
182182
|
183-
= help: there is an attribute with a similar name: `test_harness`
184-
= 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
183+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
184+
= 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`
185185

186186
error: unknown attribute `rust2018`
187187
--> $DIR/check-attr.rs:43:1
@@ -222,8 +222,8 @@ LL | | /// boo
222222
LL | | /// ```
223223
| |_______^
224224
|
225-
= help: there is an attribute with a similar name: `should_panic`
226-
= 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
225+
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
226+
= 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`
227227

228228
error: aborting due to 15 previous errors
229229

‎tests/rustdoc-ui/lints/check-fail.stderr

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ LL | | //! let x = 12;
3131
LL | | //! ```
3232
| |_______^
3333
|
34-
= help: there is an attribute with a similar name: `test_harness`
35-
= 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
34+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
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
note: the lint level is defined here
3737
--> $DIR/check-fail.rs:6:9
3838
|
@@ -51,8 +51,8 @@ LL | | /// let x = 12;
5151
LL | | /// ```
5252
| |_______^
5353
|
54-
= help: there is an attribute with a similar name: `test_harness`
55-
= 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
54+
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
55+
= 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`
5656

5757
error: aborting due to 4 previous errors
5858

0 commit comments

Comments
 (0)
Please sign in to comment.