Skip to content

Commit ee683ef

Browse files
jyn514jyn514
committed
Say 'prefix with kind@' instead of 'prefix with the item kind'
This is both more specific and easier to read.
1 parent d67eb1f commit ee683ef

8 files changed

+73
-100
lines changed

‎src/librustdoc/passes/collect_intra_doc_links.rs

+39-18
Original file line numberDiff line numberDiff line change
@@ -1328,21 +1328,16 @@ impl Disambiguator {
13281328
}
13291329
}
13301330

1331-
/// Return (description of the change, suggestion)
1332-
fn suggestion_for(self, path_str: &str) -> (&'static str, String) {
1333-
const PREFIX: &str = "prefix with the item kind";
1334-
const FUNCTION: &str = "add parentheses";
1335-
const MACRO: &str = "add an exclamation mark";
1336-
1331+
fn suggestion(self) -> Suggestion {
13371332
let kind = match self {
1338-
Disambiguator::Primitive => return (PREFIX, format!("prim@{}", path_str)),
1333+
Disambiguator::Primitive => return Suggestion::Prefix("prim"),
13391334
Disambiguator::Kind(kind) => kind,
13401335
Disambiguator::Namespace(_) => panic!("display_for cannot be used on namespaces"),
13411336
};
13421337
if kind == DefKind::Macro(MacroKind::Bang) {
1343-
return (MACRO, format!("{}!", path_str));
1338+
return Suggestion::Macro;
13441339
} else if kind == DefKind::Fn || kind == DefKind::AssocFn {
1345-
return (FUNCTION, format!("{}()", path_str));
1340+
return Suggestion::Function;
13461341
}
13471342

13481343
let prefix = match kind {
@@ -1367,8 +1362,7 @@ impl Disambiguator {
13671362
},
13681363
};
13691364

1370-
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
1371-
(PREFIX, format!("{}@{}", prefix, path_str))
1365+
Suggestion::Prefix(prefix)
13721366
}
13731367

13741368
fn ns(self) -> Namespace {
@@ -1400,6 +1394,31 @@ impl Disambiguator {
14001394
}
14011395
}
14021396

1397+
enum Suggestion {
1398+
Prefix(&'static str),
1399+
Function,
1400+
Macro,
1401+
}
1402+
1403+
impl Suggestion {
1404+
fn descr(&self) -> Cow<'static, str> {
1405+
match self {
1406+
Self::Prefix(x) => format!("prefix with `{}@`", x).into(),
1407+
Self::Function => "add parentheses".into(),
1408+
Self::Macro => "add an exclamation mark".into(),
1409+
}
1410+
}
1411+
1412+
fn as_help(&self, path_str: &str) -> String {
1413+
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
1414+
match self {
1415+
Self::Prefix(prefix) => format!("{}@{}", prefix, path_str),
1416+
Self::Function => format!("{}()", path_str),
1417+
Self::Macro => format!("{}!", path_str),
1418+
}
1419+
}
1420+
}
1421+
14031422
/// Reports a diagnostic for an intra-doc link.
14041423
///
14051424
/// If no link range is provided, or the source span of the link cannot be determined, the span of
@@ -1695,18 +1714,20 @@ fn suggest_disambiguator(
16951714
sp: Option<rustc_span::Span>,
16961715
link_range: &Option<Range<usize>>,
16971716
) {
1698-
let (action, mut suggestion) = disambiguator.suggestion_for(path_str);
1699-
let help = format!("to link to the {}, {}", disambiguator.descr(), action);
1717+
let suggestion = disambiguator.suggestion();
1718+
let help = format!("to link to the {}, {}", disambiguator.descr(), suggestion.descr());
17001719

17011720
if let Some(sp) = sp {
17021721
let link_range = link_range.as_ref().expect("must have a link range if we have a span");
1703-
if dox.bytes().nth(link_range.start) == Some(b'`') {
1704-
suggestion = format!("`{}`", suggestion);
1705-
}
1722+
let msg = if dox.bytes().nth(link_range.start) == Some(b'`') {
1723+
format!("`{}`", suggestion.as_help(path_str))
1724+
} else {
1725+
suggestion.as_help(path_str)
1726+
};
17061727

1707-
diag.span_suggestion(sp, &help, suggestion, Applicability::MaybeIncorrect);
1728+
diag.span_suggestion(sp, &help, msg, Applicability::MaybeIncorrect);
17081729
} else {
1709-
diag.help(&format!("{}: {}", help, suggestion));
1730+
diag.help(&format!("{}: {}", help, suggestion.as_help(path_str)));
17101731
}
17111732
}
17121733

‎src/test/rustdoc-ui/intra-link-errors.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242

4343
/// [S!]
4444
//~^ ERROR unresolved link
45-
//~| HELP to link to the struct, prefix with the item kind
45+
//~| HELP to link to the struct, prefix with `struct@`
4646
//~| NOTE this link resolves to the struct `S`
4747
pub fn f() {}
4848
#[derive(Debug)]

‎src/test/rustdoc-ui/intra-link-errors.stderr

+1-5
Original file line numberDiff line numberDiff line change
@@ -79,13 +79,9 @@ error: unresolved link to `S`
7979
--> $DIR/intra-link-errors.rs:44:6
8080
|
8181
LL | /// [S!]
82-
| ^^
82+
| ^^ help: to link to the struct, prefix with `struct@`: `struct@S`
8383
|
8484
= note: this link resolves to the struct `S`, which is not in the macro namespace
85-
help: to link to the struct, prefix with the item kind
86-
|
87-
LL | /// [struct@S]
88-
| ^^^^^^^^
8985

9086
error: unresolved link to `T::g`
9187
--> $DIR/intra-link-errors.rs:62:6

‎src/test/rustdoc-ui/intra-link-prim-conflict.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@
1818
1919
/// [struct@char]
2020
//~^ ERROR incompatible link
21-
//~| HELP prefix with the item kind
21+
//~| HELP prefix with `mod@`
2222
//~| NOTE resolved to a module
2323
pub mod char {}
2424

2525
pub mod inner {
2626
//! [struct@char]
2727
//~^ ERROR incompatible link
28-
//~| HELP prefix with the item kind
28+
//~| HELP prefix with `prim@`
2929
//~| NOTE resolved to a builtin type
3030
}

‎src/test/rustdoc-ui/intra-link-prim-conflict.stderr

+6-14
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@ note: the lint level is defined here
99
|
1010
LL | #![deny(broken_intra_doc_links)]
1111
| ^^^^^^^^^^^^^^^^^^^^^^
12-
help: to link to the module, prefix with the item kind
12+
help: to link to the module, prefix with `mod@`
1313
|
1414
LL | /// [mod@char]
1515
| ^^^^^^^^
16-
help: to link to the builtin type, prefix with the item kind
16+
help: to link to the builtin type, prefix with `prim@`
1717
|
1818
LL | /// [prim@char]
1919
| ^^^^^^^^^
@@ -24,11 +24,11 @@ error: `char` is both a module and a builtin type
2424
LL | /// [type@char]
2525
| ^^^^^^^^^ ambiguous link
2626
|
27-
help: to link to the module, prefix with the item kind
27+
help: to link to the module, prefix with `mod@`
2828
|
2929
LL | /// [mod@char]
3030
| ^^^^^^^^
31-
help: to link to the builtin type, prefix with the item kind
31+
help: to link to the builtin type, prefix with `prim@`
3232
|
3333
LL | /// [prim@char]
3434
| ^^^^^^^^^
@@ -37,25 +37,17 @@ error: incompatible link kind for `char`
3737
--> $DIR/intra-link-prim-conflict.rs:19:6
3838
|
3939
LL | /// [struct@char]
40-
| ^^^^^^^^^^^
40+
| ^^^^^^^^^^^ help: to link to the module, prefix with `mod@`: `mod@char`
4141
|
4242
= note: this link resolved to a module, which is not a struct
43-
help: to link to the module, prefix with the item kind
44-
|
45-
LL | /// [mod@char]
46-
| ^^^^^^^^
4743

4844
error: incompatible link kind for `char`
4945
--> $DIR/intra-link-prim-conflict.rs:26:10
5046
|
5147
LL | //! [struct@char]
52-
| ^^^^^^^^^^^
48+
| ^^^^^^^^^^^ help: to link to the builtin type, prefix with `prim@`: `prim@char`
5349
|
5450
= note: this link resolved to a builtin type, which is not a struct
55-
help: to link to the builtin type, prefix with the item kind
56-
|
57-
LL | //! [prim@char]
58-
| ^^^^^^^^^
5951

6052
error: aborting due to 4 previous errors
6153

‎src/test/rustdoc-ui/intra-links-ambiguity.stderr

+6-6
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ note: the lint level is defined here
99
|
1010
LL | #![deny(broken_intra_doc_links)]
1111
| ^^^^^^^^^^^^^^^^^^^^^^
12-
help: to link to the struct, prefix with the item kind
12+
help: to link to the struct, prefix with `struct@`
1313
|
1414
LL | /// [`struct@ambiguous`] is ambiguous.
1515
| ^^^^^^^^^^^^^^^^^^
@@ -24,7 +24,7 @@ error: `ambiguous` is both a struct and a function
2424
LL | /// [ambiguous] is ambiguous.
2525
| ^^^^^^^^^ ambiguous link
2626
|
27-
help: to link to the struct, prefix with the item kind
27+
help: to link to the struct, prefix with `struct@`
2828
|
2929
LL | /// [struct@ambiguous] is ambiguous.
3030
| ^^^^^^^^^^^^^^^^
@@ -39,7 +39,7 @@ error: `multi_conflict` is a struct, a function, and a macro
3939
LL | /// [`multi_conflict`] is a three-way conflict.
4040
| ^^^^^^^^^^^^^^^^ ambiguous link
4141
|
42-
help: to link to the struct, prefix with the item kind
42+
help: to link to the struct, prefix with `struct@`
4343
|
4444
LL | /// [`struct@multi_conflict`] is a three-way conflict.
4545
| ^^^^^^^^^^^^^^^^^^^^^^^
@@ -58,11 +58,11 @@ error: `type_and_value` is both a module and a constant
5858
LL | /// Ambiguous [type_and_value].
5959
| ^^^^^^^^^^^^^^ ambiguous link
6060
|
61-
help: to link to the module, prefix with the item kind
61+
help: to link to the module, prefix with `mod@`
6262
|
6363
LL | /// Ambiguous [mod@type_and_value].
6464
| ^^^^^^^^^^^^^^^^^^
65-
help: to link to the constant, prefix with the item kind
65+
help: to link to the constant, prefix with `const@`
6666
|
6767
LL | /// Ambiguous [const@type_and_value].
6868
| ^^^^^^^^^^^^^^^^^^^^
@@ -73,7 +73,7 @@ error: `foo::bar` is both an enum and a function
7373
LL | /// Ambiguous non-implied shortcut link [`foo::bar`].
7474
| ^^^^^^^^^^ ambiguous link
7575
|
76-
help: to link to the enum, prefix with the item kind
76+
help: to link to the enum, prefix with `enum@`
7777
|
7878
LL | /// Ambiguous non-implied shortcut link [`enum@foo::bar`].
7979
| ^^^^^^^^^^^^^^^

‎src/test/rustdoc-ui/intra-links-disambiguator-mismatch.rs

+9-9
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,27 @@ trait T {}
1414
/// Link to [struct@S]
1515
//~^ ERROR incompatible link kind for `S`
1616
//~| NOTE this link resolved
17-
//~| HELP prefix with the item kind
17+
//~| HELP prefix with `enum@`
1818

1919
/// Link to [mod@S]
2020
//~^ ERROR incompatible link kind for `S`
2121
//~| NOTE this link resolved
22-
//~| HELP prefix with the item kind
22+
//~| HELP prefix with `enum@`
2323

2424
/// Link to [union@S]
2525
//~^ ERROR incompatible link kind for `S`
2626
//~| NOTE this link resolved
27-
//~| HELP prefix with the item kind
27+
//~| HELP prefix with `enum@`
2828

2929
/// Link to [trait@S]
3030
//~^ ERROR incompatible link kind for `S`
3131
//~| NOTE this link resolved
32-
//~| HELP prefix with the item kind
32+
//~| HELP prefix with `enum@`
3333

3434
/// Link to [struct@T]
3535
//~^ ERROR incompatible link kind for `T`
3636
//~| NOTE this link resolved
37-
//~| HELP prefix with the item kind
37+
//~| HELP prefix with `trait@`
3838

3939
/// Link to [derive@m]
4040
//~^ ERROR incompatible link kind for `m`
@@ -44,22 +44,22 @@ trait T {}
4444
/// Link to [const@s]
4545
//~^ ERROR incompatible link kind for `s`
4646
//~| NOTE this link resolved
47-
//~| HELP prefix with the item kind
47+
//~| HELP prefix with `static@`
4848

4949
/// Link to [static@c]
5050
//~^ ERROR incompatible link kind for `c`
5151
//~| NOTE this link resolved
52-
//~| HELP prefix with the item kind
52+
//~| HELP prefix with `const@`
5353

5454
/// Link to [fn@c]
5555
//~^ ERROR incompatible link kind for `c`
5656
//~| NOTE this link resolved
57-
//~| HELP prefix with the item kind
57+
//~| HELP prefix with `const@`
5858

5959
/// Link to [c()]
6060
//~^ ERROR incompatible link kind for `c`
6161
//~| NOTE this link resolved
62-
//~| HELP prefix with the item kind
62+
//~| HELP prefix with `const@`
6363

6464
/// Link to [const@f]
6565
//~^ ERROR incompatible link kind for `f`

0 commit comments

Comments
 (0)