1
Fork 0

Say 'prefix with kind@' instead of 'prefix with the item kind'

This is both more specific and easier to read.
This commit is contained in:
Joshua Nelson 2020-08-28 00:53:36 -04:00
parent d67eb1f148
commit ee683ef853
8 changed files with 73 additions and 100 deletions

View file

@ -1328,21 +1328,16 @@ impl Disambiguator {
} }
} }
/// Return (description of the change, suggestion) fn suggestion(self) -> Suggestion {
fn suggestion_for(self, path_str: &str) -> (&'static str, String) {
const PREFIX: &str = "prefix with the item kind";
const FUNCTION: &str = "add parentheses";
const MACRO: &str = "add an exclamation mark";
let kind = match self { let kind = match self {
Disambiguator::Primitive => return (PREFIX, format!("prim@{}", path_str)), Disambiguator::Primitive => return Suggestion::Prefix("prim"),
Disambiguator::Kind(kind) => kind, Disambiguator::Kind(kind) => kind,
Disambiguator::Namespace(_) => panic!("display_for cannot be used on namespaces"), Disambiguator::Namespace(_) => panic!("display_for cannot be used on namespaces"),
}; };
if kind == DefKind::Macro(MacroKind::Bang) { if kind == DefKind::Macro(MacroKind::Bang) {
return (MACRO, format!("{}!", path_str)); return Suggestion::Macro;
} else if kind == DefKind::Fn || kind == DefKind::AssocFn { } else if kind == DefKind::Fn || kind == DefKind::AssocFn {
return (FUNCTION, format!("{}()", path_str)); return Suggestion::Function;
} }
let prefix = match kind { let prefix = match kind {
@ -1367,8 +1362,7 @@ impl Disambiguator {
}, },
}; };
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@` Suggestion::Prefix(prefix)
(PREFIX, format!("{}@{}", prefix, path_str))
} }
fn ns(self) -> Namespace { fn ns(self) -> Namespace {
@ -1400,6 +1394,31 @@ impl Disambiguator {
} }
} }
enum Suggestion {
Prefix(&'static str),
Function,
Macro,
}
impl Suggestion {
fn descr(&self) -> Cow<'static, str> {
match self {
Self::Prefix(x) => format!("prefix with `{}@`", x).into(),
Self::Function => "add parentheses".into(),
Self::Macro => "add an exclamation mark".into(),
}
}
fn as_help(&self, path_str: &str) -> String {
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
match self {
Self::Prefix(prefix) => format!("{}@{}", prefix, path_str),
Self::Function => format!("{}()", path_str),
Self::Macro => format!("{}!", path_str),
}
}
}
/// Reports a diagnostic for an intra-doc link. /// Reports a diagnostic for an intra-doc link.
/// ///
/// If no link range is provided, or the source span of the link cannot be determined, the span of /// 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(
sp: Option<rustc_span::Span>, sp: Option<rustc_span::Span>,
link_range: &Option<Range<usize>>, link_range: &Option<Range<usize>>,
) { ) {
let (action, mut suggestion) = disambiguator.suggestion_for(path_str); let suggestion = disambiguator.suggestion();
let help = format!("to link to the {}, {}", disambiguator.descr(), action); let help = format!("to link to the {}, {}", disambiguator.descr(), suggestion.descr());
if let Some(sp) = sp { if let Some(sp) = sp {
let link_range = link_range.as_ref().expect("must have a link range if we have a span"); let link_range = link_range.as_ref().expect("must have a link range if we have a span");
if dox.bytes().nth(link_range.start) == Some(b'`') { let msg = if dox.bytes().nth(link_range.start) == Some(b'`') {
suggestion = format!("`{}`", suggestion); format!("`{}`", suggestion.as_help(path_str))
} } else {
suggestion.as_help(path_str)
};
diag.span_suggestion(sp, &help, suggestion, Applicability::MaybeIncorrect); diag.span_suggestion(sp, &help, msg, Applicability::MaybeIncorrect);
} else { } else {
diag.help(&format!("{}: {}", help, suggestion)); diag.help(&format!("{}: {}", help, suggestion.as_help(path_str)));
} }
} }

View file

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

View file

@ -79,13 +79,9 @@ error: unresolved link to `S`
--> $DIR/intra-link-errors.rs:44:6 --> $DIR/intra-link-errors.rs:44:6
| |
LL | /// [S!] LL | /// [S!]
| ^^ | ^^ help: to link to the struct, prefix with `struct@`: `struct@S`
| |
= note: this link resolves to the struct `S`, which is not in the macro namespace = note: this link resolves to the struct `S`, which is not in the macro namespace
help: to link to the struct, prefix with the item kind
|
LL | /// [struct@S]
| ^^^^^^^^
error: unresolved link to `T::g` error: unresolved link to `T::g`
--> $DIR/intra-link-errors.rs:62:6 --> $DIR/intra-link-errors.rs:62:6

View file

@ -18,13 +18,13 @@
/// [struct@char] /// [struct@char]
//~^ ERROR incompatible link //~^ ERROR incompatible link
//~| HELP prefix with the item kind //~| HELP prefix with `mod@`
//~| NOTE resolved to a module //~| NOTE resolved to a module
pub mod char {} pub mod char {}
pub mod inner { pub mod inner {
//! [struct@char] //! [struct@char]
//~^ ERROR incompatible link //~^ ERROR incompatible link
//~| HELP prefix with the item kind //~| HELP prefix with `prim@`
//~| NOTE resolved to a builtin type //~| NOTE resolved to a builtin type
} }

View file

@ -9,11 +9,11 @@ note: the lint level is defined here
| |
LL | #![deny(broken_intra_doc_links)] LL | #![deny(broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^
help: to link to the module, prefix with the item kind help: to link to the module, prefix with `mod@`
| |
LL | /// [mod@char] LL | /// [mod@char]
| ^^^^^^^^ | ^^^^^^^^
help: to link to the builtin type, prefix with the item kind help: to link to the builtin type, prefix with `prim@`
| |
LL | /// [prim@char] LL | /// [prim@char]
| ^^^^^^^^^ | ^^^^^^^^^
@ -24,11 +24,11 @@ error: `char` is both a module and a builtin type
LL | /// [type@char] LL | /// [type@char]
| ^^^^^^^^^ ambiguous link | ^^^^^^^^^ ambiguous link
| |
help: to link to the module, prefix with the item kind help: to link to the module, prefix with `mod@`
| |
LL | /// [mod@char] LL | /// [mod@char]
| ^^^^^^^^ | ^^^^^^^^
help: to link to the builtin type, prefix with the item kind help: to link to the builtin type, prefix with `prim@`
| |
LL | /// [prim@char] LL | /// [prim@char]
| ^^^^^^^^^ | ^^^^^^^^^
@ -37,25 +37,17 @@ error: incompatible link kind for `char`
--> $DIR/intra-link-prim-conflict.rs:19:6 --> $DIR/intra-link-prim-conflict.rs:19:6
| |
LL | /// [struct@char] LL | /// [struct@char]
| ^^^^^^^^^^^ | ^^^^^^^^^^^ help: to link to the module, prefix with `mod@`: `mod@char`
| |
= note: this link resolved to a module, which is not a struct = note: this link resolved to a module, which is not a struct
help: to link to the module, prefix with the item kind
|
LL | /// [mod@char]
| ^^^^^^^^
error: incompatible link kind for `char` error: incompatible link kind for `char`
--> $DIR/intra-link-prim-conflict.rs:26:10 --> $DIR/intra-link-prim-conflict.rs:26:10
| |
LL | //! [struct@char] LL | //! [struct@char]
| ^^^^^^^^^^^ | ^^^^^^^^^^^ help: to link to the builtin type, prefix with `prim@`: `prim@char`
| |
= note: this link resolved to a builtin type, which is not a struct = note: this link resolved to a builtin type, which is not a struct
help: to link to the builtin type, prefix with the item kind
|
LL | //! [prim@char]
| ^^^^^^^^^
error: aborting due to 4 previous errors error: aborting due to 4 previous errors

View file

@ -9,7 +9,7 @@ note: the lint level is defined here
| |
LL | #![deny(broken_intra_doc_links)] LL | #![deny(broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^
help: to link to the struct, prefix with the item kind help: to link to the struct, prefix with `struct@`
| |
LL | /// [`struct@ambiguous`] is ambiguous. LL | /// [`struct@ambiguous`] is ambiguous.
| ^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^
@ -24,7 +24,7 @@ error: `ambiguous` is both a struct and a function
LL | /// [ambiguous] is ambiguous. LL | /// [ambiguous] is ambiguous.
| ^^^^^^^^^ ambiguous link | ^^^^^^^^^ ambiguous link
| |
help: to link to the struct, prefix with the item kind help: to link to the struct, prefix with `struct@`
| |
LL | /// [struct@ambiguous] is ambiguous. LL | /// [struct@ambiguous] is ambiguous.
| ^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^
@ -39,7 +39,7 @@ error: `multi_conflict` is a struct, a function, and a macro
LL | /// [`multi_conflict`] is a three-way conflict. LL | /// [`multi_conflict`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^ ambiguous link | ^^^^^^^^^^^^^^^^ ambiguous link
| |
help: to link to the struct, prefix with the item kind help: to link to the struct, prefix with `struct@`
| |
LL | /// [`struct@multi_conflict`] is a three-way conflict. LL | /// [`struct@multi_conflict`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^
@ -58,11 +58,11 @@ error: `type_and_value` is both a module and a constant
LL | /// Ambiguous [type_and_value]. LL | /// Ambiguous [type_and_value].
| ^^^^^^^^^^^^^^ ambiguous link | ^^^^^^^^^^^^^^ ambiguous link
| |
help: to link to the module, prefix with the item kind help: to link to the module, prefix with `mod@`
| |
LL | /// Ambiguous [mod@type_and_value]. LL | /// Ambiguous [mod@type_and_value].
| ^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^
help: to link to the constant, prefix with the item kind help: to link to the constant, prefix with `const@`
| |
LL | /// Ambiguous [const@type_and_value]. LL | /// Ambiguous [const@type_and_value].
| ^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^
@ -73,7 +73,7 @@ error: `foo::bar` is both an enum and a function
LL | /// Ambiguous non-implied shortcut link [`foo::bar`]. LL | /// Ambiguous non-implied shortcut link [`foo::bar`].
| ^^^^^^^^^^ ambiguous link | ^^^^^^^^^^ ambiguous link
| |
help: to link to the enum, prefix with the item kind help: to link to the enum, prefix with `enum@`
| |
LL | /// Ambiguous non-implied shortcut link [`enum@foo::bar`]. LL | /// Ambiguous non-implied shortcut link [`enum@foo::bar`].
| ^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^

View file

@ -14,27 +14,27 @@ trait T {}
/// Link to [struct@S] /// Link to [struct@S]
//~^ ERROR incompatible link kind for `S` //~^ ERROR incompatible link kind for `S`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `enum@`
/// Link to [mod@S] /// Link to [mod@S]
//~^ ERROR incompatible link kind for `S` //~^ ERROR incompatible link kind for `S`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `enum@`
/// Link to [union@S] /// Link to [union@S]
//~^ ERROR incompatible link kind for `S` //~^ ERROR incompatible link kind for `S`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `enum@`
/// Link to [trait@S] /// Link to [trait@S]
//~^ ERROR incompatible link kind for `S` //~^ ERROR incompatible link kind for `S`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `enum@`
/// Link to [struct@T] /// Link to [struct@T]
//~^ ERROR incompatible link kind for `T` //~^ ERROR incompatible link kind for `T`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `trait@`
/// Link to [derive@m] /// Link to [derive@m]
//~^ ERROR incompatible link kind for `m` //~^ ERROR incompatible link kind for `m`
@ -44,22 +44,22 @@ trait T {}
/// Link to [const@s] /// Link to [const@s]
//~^ ERROR incompatible link kind for `s` //~^ ERROR incompatible link kind for `s`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `static@`
/// Link to [static@c] /// Link to [static@c]
//~^ ERROR incompatible link kind for `c` //~^ ERROR incompatible link kind for `c`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `const@`
/// Link to [fn@c] /// Link to [fn@c]
//~^ ERROR incompatible link kind for `c` //~^ ERROR incompatible link kind for `c`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `const@`
/// Link to [c()] /// Link to [c()]
//~^ ERROR incompatible link kind for `c` //~^ ERROR incompatible link kind for `c`
//~| NOTE this link resolved //~| NOTE this link resolved
//~| HELP prefix with the item kind //~| HELP prefix with `const@`
/// Link to [const@f] /// Link to [const@f]
//~^ ERROR incompatible link kind for `f` //~^ ERROR incompatible link kind for `f`

View file

@ -2,7 +2,7 @@ error: incompatible link kind for `S`
--> $DIR/intra-links-disambiguator-mismatch.rs:14:14 --> $DIR/intra-links-disambiguator-mismatch.rs:14:14
| |
LL | /// Link to [struct@S] LL | /// Link to [struct@S]
| ^^^^^^^^ | ^^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/intra-links-disambiguator-mismatch.rs:1:9 --> $DIR/intra-links-disambiguator-mismatch.rs:1:9
@ -10,58 +10,38 @@ note: the lint level is defined here
LL | #![deny(broken_intra_doc_links)] LL | #![deny(broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^
= note: this link resolved to an enum, which is not a struct = note: this link resolved to an enum, which is not a struct
help: to link to the enum, prefix with the item kind
|
LL | /// Link to [enum@S]
| ^^^^^^
error: incompatible link kind for `S` error: incompatible link kind for `S`
--> $DIR/intra-links-disambiguator-mismatch.rs:19:14 --> $DIR/intra-links-disambiguator-mismatch.rs:19:14
| |
LL | /// Link to [mod@S] LL | /// Link to [mod@S]
| ^^^^^ | ^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| |
= note: this link resolved to an enum, which is not a module = note: this link resolved to an enum, which is not a module
help: to link to the enum, prefix with the item kind
|
LL | /// Link to [enum@S]
| ^^^^^^
error: incompatible link kind for `S` error: incompatible link kind for `S`
--> $DIR/intra-links-disambiguator-mismatch.rs:24:14 --> $DIR/intra-links-disambiguator-mismatch.rs:24:14
| |
LL | /// Link to [union@S] LL | /// Link to [union@S]
| ^^^^^^^ | ^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| |
= note: this link resolved to an enum, which is not a union = note: this link resolved to an enum, which is not a union
help: to link to the enum, prefix with the item kind
|
LL | /// Link to [enum@S]
| ^^^^^^
error: incompatible link kind for `S` error: incompatible link kind for `S`
--> $DIR/intra-links-disambiguator-mismatch.rs:29:14 --> $DIR/intra-links-disambiguator-mismatch.rs:29:14
| |
LL | /// Link to [trait@S] LL | /// Link to [trait@S]
| ^^^^^^^ | ^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| |
= note: this link resolved to an enum, which is not a trait = note: this link resolved to an enum, which is not a trait
help: to link to the enum, prefix with the item kind
|
LL | /// Link to [enum@S]
| ^^^^^^
error: incompatible link kind for `T` error: incompatible link kind for `T`
--> $DIR/intra-links-disambiguator-mismatch.rs:34:14 --> $DIR/intra-links-disambiguator-mismatch.rs:34:14
| |
LL | /// Link to [struct@T] LL | /// Link to [struct@T]
| ^^^^^^^^ | ^^^^^^^^ help: to link to the trait, prefix with `trait@`: `trait@T`
| |
= note: this link resolved to a trait, which is not a struct = note: this link resolved to a trait, which is not a struct
help: to link to the trait, prefix with the item kind
|
LL | /// Link to [trait@T]
| ^^^^^^^
error: incompatible link kind for `m` error: incompatible link kind for `m`
--> $DIR/intra-links-disambiguator-mismatch.rs:39:14 --> $DIR/intra-links-disambiguator-mismatch.rs:39:14
@ -75,49 +55,33 @@ error: incompatible link kind for `s`
--> $DIR/intra-links-disambiguator-mismatch.rs:44:14 --> $DIR/intra-links-disambiguator-mismatch.rs:44:14
| |
LL | /// Link to [const@s] LL | /// Link to [const@s]
| ^^^^^^^ | ^^^^^^^ help: to link to the static, prefix with `static@`: `static@s`
| |
= note: this link resolved to a static, which is not a constant = note: this link resolved to a static, which is not a constant
help: to link to the static, prefix with the item kind
|
LL | /// Link to [static@s]
| ^^^^^^^^
error: incompatible link kind for `c` error: incompatible link kind for `c`
--> $DIR/intra-links-disambiguator-mismatch.rs:49:14 --> $DIR/intra-links-disambiguator-mismatch.rs:49:14
| |
LL | /// Link to [static@c] LL | /// Link to [static@c]
| ^^^^^^^^ | ^^^^^^^^ help: to link to the constant, prefix with `const@`: `const@c`
| |
= note: this link resolved to a constant, which is not a static = note: this link resolved to a constant, which is not a static
help: to link to the constant, prefix with the item kind
|
LL | /// Link to [const@c]
| ^^^^^^^
error: incompatible link kind for `c` error: incompatible link kind for `c`
--> $DIR/intra-links-disambiguator-mismatch.rs:54:14 --> $DIR/intra-links-disambiguator-mismatch.rs:54:14
| |
LL | /// Link to [fn@c] LL | /// Link to [fn@c]
| ^^^^ | ^^^^ help: to link to the constant, prefix with `const@`: `const@c`
| |
= note: this link resolved to a constant, which is not a function = note: this link resolved to a constant, which is not a function
help: to link to the constant, prefix with the item kind
|
LL | /// Link to [const@c]
| ^^^^^^^
error: incompatible link kind for `c` error: incompatible link kind for `c`
--> $DIR/intra-links-disambiguator-mismatch.rs:59:14 --> $DIR/intra-links-disambiguator-mismatch.rs:59:14
| |
LL | /// Link to [c()] LL | /// Link to [c()]
| ^^^ | ^^^ help: to link to the constant, prefix with `const@`: `const@c`
| |
= note: this link resolved to a constant, which is not a function = note: this link resolved to a constant, which is not a function
help: to link to the constant, prefix with the item kind
|
LL | /// Link to [const@c]
| ^^^^^^^
error: incompatible link kind for `f` error: incompatible link kind for `f`
--> $DIR/intra-links-disambiguator-mismatch.rs:64:14 --> $DIR/intra-links-disambiguator-mismatch.rs:64:14