From a091fd25cae34ebdc3f158e623743d51428952ff Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 15 Apr 2023 12:07:30 +0200 Subject: [PATCH 1/2] Add list of supported disambiguators and suffixes for intra-doc links in the rustdoc book --- .../src/write-documentation/linking-to-items-by-name.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md index eb2285ef90646..72157b5cd9bce 100644 --- a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md +++ b/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()`] From 1531c95c5d3f4e9ef4cfc122c35947e7b9cca53e Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sat, 15 Apr 2023 15:52:27 +0200 Subject: [PATCH 2/2] Add code comment to remind contributors to update rustdoc book if they update the disambiguators list --- src/librustdoc/passes/collect_intra_doc_links.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs index 2cd9c8a878187..3b7226df65a3d 100644 --- a/src/librustdoc/passes/collect_intra_doc_links.rs +++ b/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)),