Rollup merge of rust-lang#110348 - GuillaumeGomez:disambiguators-suff…

…ixes-rustdoc-book, r=Manishearth

Add list of supported disambiguators and suffixes for intra-doc links in the rustdoc book

This information is otherwise only provided in case an error occurs, which isn't great.

r? `@notriddle`

src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md

@@ -88,13 +88,16 @@ fn Foo() {}
 ```
 
 These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` will be
-rendered as `Foo`.
+rendered as `Foo`. The following prefixes are available: `struct`, `enum`, `trait`, `union`,
+`mod`, `module`, `const`, `constant`, `fn`, `function`, `method`, `derive`, `type`, `value`,
+`macro`, `prim` or `primitive`.
 
 You can also disambiguate for functions by adding `()` after the function name,
-or for macros by adding `!` after the macro name:
+or for macros by adding `!` after the macro name. The macro `!` can be followed by `()`, `{}`,
+or `[]`. Example:
 
 ```rust
-/// This is different from [`foo!`]
+/// This is different from [`foo!()`].
 fn foo() {}
 
 /// This is different from [`foo()`]

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -1419,6 +1419,7 @@ impl Disambiguator {
  if let Some(idx) = link.find('@') {
  let (prefix, rest) = link.split_at(idx);
  let d = match prefix {
+ // If you update this list, please also update the relevant rustdoc book section!
  "struct" => Kind(DefKind::Struct),
  "enum" => Kind(DefKind::Enum),
  "trait" => Kind(DefKind::Trait),
@@ -1437,6 +1438,7 @@ impl Disambiguator {
  Ok(Some((d, &rest[1..], &rest[1..])))
  } else {
  let suffixes = [
+ // If you update this list, please also update the relevant rustdoc book section!
  ("!()", DefKind::Macro(MacroKind::Bang)),
  ("!{}", DefKind::Macro(MacroKind::Bang)),
  ("![]", DefKind::Macro(MacroKind::Bang)),