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

This is both more specific and easier to read.

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -1328,21 +1328,16 @@ fn from_res(res: Res) -> Self {
         }
     }
 
-    /// Return (description of the change, 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";
-
+    fn suggestion(self) -> Suggestion {
         let kind = match self {
-            Disambiguator::Primitive => return (PREFIX, format!("prim@{}", path_str)),
+            Disambiguator::Primitive => return Suggestion::Prefix("prim"),
             Disambiguator::Kind(kind) => kind,
             Disambiguator::Namespace(_) => panic!("display_for cannot be used on namespaces"),
         };
         if kind == DefKind::Macro(MacroKind::Bang) {
-            return (MACRO, format!("{}!", path_str));
+            return Suggestion::Macro;
         } else if kind == DefKind::Fn || kind == DefKind::AssocFn {
-            return (FUNCTION, format!("{}()", path_str));
+            return Suggestion::Function;
         }
 
         let prefix = match kind {
@@ -1367,8 +1362,7 @@ fn suggestion_for(self, path_str: &str) -> (&'static str, String) {
             },
         };
 
-        // FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
-        (PREFIX, format!("{}@{}", prefix, path_str))
+        Suggestion::Prefix(prefix)
     }
 
     fn ns(self) -> Namespace {
@@ -1400,6 +1394,31 @@ fn descr(self) -> &'static str {
     }
 }
 
+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.
 ///
 /// 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>,
     link_range: &Option<Range<usize>>,
 ) {
-    let (action, mut suggestion) = disambiguator.suggestion_for(path_str);
-    let help = format!("to link to the {}, {}", disambiguator.descr(), action);
+    let suggestion = disambiguator.suggestion();
+    let help = format!("to link to the {}, {}", disambiguator.descr(), suggestion.descr());
 
     if let Some(sp) = sp {
         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'`') {
-            suggestion = format!("`{}`", suggestion);
-        }
+        let msg = if dox.bytes().nth(link_range.start) == Some(b'`') {
+            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 {
-        diag.help(&format!("{}: {}", help, suggestion));
+        diag.help(&format!("{}: {}", help, suggestion.as_help(path_str)));
     }
 }
 

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

@@ -42,7 +42,7 @@
 
 /// [S!]
 //~^ 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`
 pub fn f() {}
 #[derive(Debug)]

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

@@ -79,13 +79,9 @@ error: unresolved link to `S`
   --> $DIR/intra-link-errors.rs:44:6
    |
 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
-help: to link to the struct, prefix with the item kind
-   |
-LL | /// [struct@S]
-   |      ^^^^^^^^
 
 error: unresolved link to `T::g`
   --> $DIR/intra-link-errors.rs:62:6

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

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

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

@@ -9,11 +9,11 @@ note: the lint level is defined here
    |
 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]
    |      ^^^^^^^^
-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]
    |      ^^^^^^^^^
@@ -24,11 +24,11 @@ error: `char` is both a module and a builtin type
 LL | /// [type@char]
    |      ^^^^^^^^^ 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]
    |      ^^^^^^^^
-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]
    |      ^^^^^^^^^
@@ -37,25 +37,17 @@ error: incompatible link kind for `char`
   --> $DIR/intra-link-prim-conflict.rs:19:6
    |
 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
-help: to link to the module, prefix with the item kind
-   |
-LL | /// [mod@char]
-   |      ^^^^^^^^
 
 error: incompatible link kind for `char`
   --> $DIR/intra-link-prim-conflict.rs:26:10
    |
 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
-help: to link to the builtin type, prefix with the item kind
-   |
-LL |     //! [prim@char]
-   |          ^^^^^^^^^
 
 error: aborting due to 4 previous errors
 

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

@@ -9,7 +9,7 @@ note: the lint level is defined here
    |
 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.
    |      ^^^^^^^^^^^^^^^^^^
@@ -24,7 +24,7 @@ error: `ambiguous` is both a struct and a function
 LL | /// [ambiguous] is ambiguous.
    |      ^^^^^^^^^ 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.
    |      ^^^^^^^^^^^^^^^^
@@ -39,7 +39,7 @@ error: `multi_conflict` is a struct, a function, and a macro
 LL | /// [`multi_conflict`] is a three-way conflict.
    |      ^^^^^^^^^^^^^^^^ 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.
    |      ^^^^^^^^^^^^^^^^^^^^^^^
@@ -58,11 +58,11 @@ error: `type_and_value` is both a module and a constant
 LL | /// Ambiguous [type_and_value].
    |                ^^^^^^^^^^^^^^ 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].
    |                ^^^^^^^^^^^^^^^^^^
-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].
    |                ^^^^^^^^^^^^^^^^^^^^
@@ -73,7 +73,7 @@ error: `foo::bar` is both an enum and a function
 LL | /// Ambiguous non-implied shortcut link [`foo::bar`].
    |                                          ^^^^^^^^^^ 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`].
    |                                          ^^^^^^^^^^^^^^^

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

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

src/test/rustdoc-ui/intra-links-disambiguator-mismatch.stderr

@@ -2,7 +2,7 @@ error: incompatible link kind for `S`
   --> $DIR/intra-links-disambiguator-mismatch.rs:14:14
    |
 LL | /// Link to [struct@S]
-   |              ^^^^^^^^
+   |              ^^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
    |
 note: the lint level is defined here
   --> $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)]
    |         ^^^^^^^^^^^^^^^^^^^^^^
    = 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`
   --> $DIR/intra-links-disambiguator-mismatch.rs:19:14
    |
 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
-help: to link to the enum, prefix with the item kind
-   |
-LL | /// Link to [enum@S]
-   |              ^^^^^^
 
 error: incompatible link kind for `S`
   --> $DIR/intra-links-disambiguator-mismatch.rs:24:14
    |
 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
-help: to link to the enum, prefix with the item kind
-   |
-LL | /// Link to [enum@S]
-   |              ^^^^^^
 
 error: incompatible link kind for `S`
   --> $DIR/intra-links-disambiguator-mismatch.rs:29:14
    |
 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
-help: to link to the enum, prefix with the item kind
-   |
-LL | /// Link to [enum@S]
-   |              ^^^^^^
 
 error: incompatible link kind for `T`
   --> $DIR/intra-links-disambiguator-mismatch.rs:34:14
    |
 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
-help: to link to the trait, prefix with the item kind
-   |
-LL | /// Link to [trait@T]
-   |              ^^^^^^^
 
 error: incompatible link kind for `m`
   --> $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
    |
 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
-help: to link to the static, prefix with the item kind
-   |
-LL | /// Link to [static@s]
-   |              ^^^^^^^^
 
 error: incompatible link kind for `c`
   --> $DIR/intra-links-disambiguator-mismatch.rs:49:14
    |
 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
-help: to link to the constant, prefix with the item kind
-   |
-LL | /// Link to [const@c]
-   |              ^^^^^^^
 
 error: incompatible link kind for `c`
   --> $DIR/intra-links-disambiguator-mismatch.rs:54:14
    |
 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
-help: to link to the constant, prefix with the item kind
-   |
-LL | /// Link to [const@c]
-   |              ^^^^^^^
 
 error: incompatible link kind for `c`
   --> $DIR/intra-links-disambiguator-mismatch.rs:59:14
    |
 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
-help: to link to the constant, prefix with the item kind
-   |
-LL | /// Link to [const@c]
-   |              ^^^^^^^
 
 error: incompatible link kind for `f`
   --> $DIR/intra-links-disambiguator-mismatch.rs:64:14