Update intra-doc link documentation to match the implementation

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

@@ -1,7 +1,7 @@
 # Linking to items by name
 
 Rustdoc is capable of directly linking to other rustdoc pages using the path of
-the item as a link.
+the item as a link. This is referred to as an 'intra-doc link'.
 
 For example, in the following code all of the links will link to the rustdoc page for `Bar`:
 
@@ -24,11 +24,29 @@ pub struct Foo4;
 pub struct Bar;
 ```
 
+Unlike normal Markdown, `[bar][Bar]` syntax is also supported without needing a
+`[Bar]: ...` reference link, and links are case-sensitive.
+
 Backticks around the link will be stripped, so ``[`Option`]`` will correctly
 link to `Option`.
 
-You can refer to anything in scope, and use paths, including `Self`, `self`,
-`super`, and `crate`. You may also use `foo()` and `foo!()` to refer to methods/functions and macros, respectively.
+## Valid links
+
+You can refer to anything in scope, and use paths, including `Self`, `self`, `super`, and
+`crate`. Associated items (functions, types, and constants) are supported, but [not for blanket
+trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which
+have no path and cannot be imported:
+
+- [`slice`](../std/primitive.slice.html)
+- [`array`](../std/primitive.array.html)
+- [`tuple`](../std/primitive.tuple.html)
+- [`unit`](../std/primitive.unit.html)
+- [`fn`](../std/primitive.fn.html)
+- [`pointer`](../std/primitive.pointer.html), `*`, `*const`, or `*mut`
+- [`reference`](../std/primitive.reference.html), `&`, or `&mut`
+- [`never`](../std/primitive.never.html) or `!`
+
+[#79682]: https://github.com/rust-lang/rust/pull/79682
 
 You can also refer to items with generic parameters like `Vec<T>`. The link will
 resolve as if you had written ``[`Vec<T>`](Vec)``. Fully-qualified syntax (for example,
@@ -53,7 +71,7 @@ impl<T> AsyncReceiver<T> {
 }
 ```
 
-You can also link to sections using URL fragment specifiers:
+Rustdoc allows using URL fragment specifiers, just like a normal link:
 
 ```rust
 /// This is a special implementation of [positional parameters].
@@ -62,9 +80,11 @@ You can also link to sections using URL fragment specifiers:
 struct MySpecialFormatter;
 ```
 
-Paths in Rust have three namespaces: type, value, and macro. Item names must be
-unique within their namespace, but can overlap with items outside of their
-namespace. In case of ambiguity, rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, `fn@`, `function@`, `mod@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`:
+## Namespaces and Disambiguators
+
+Paths in Rust have three namespaces: type, value, and macro. Item names must be unique within
+their namespace, but can overlap with items in other namespaces. In case of ambiguity,
+rustdoc will warn about the ambiguity and ask you to disambiguate.
 
 ```rust
 /// See also: [`Foo`](struct@Foo)
@@ -76,19 +96,66 @@ struct Foo {}
 fn Foo() {}
 ```
 
+The following prefixes can be used:
+
+- `struct@`
+- `enum@`
+- `type@`
+- `trait@`
+- `union@`
+- `const@`
+- `static@`
+- `value@`
+- `fn@` / `function@` / `method@`
+- `mod@` / `module@`
+- `prim@` / `primitive@`
+- `macro@`
+- `derive@`
+
+These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]`
+will be rendered as `Foo`.
+
 You can also disambiguate for functions by adding `()` after the function name,
 or for macros by adding `!` after the macro name:
 
 ```rust
-/// See also: [`Foo`](struct@Foo)
-struct Bar;
+/// This is different from [`foo!`]
+fn foo() {}
 
-/// This is different from [`Foo()`]
-struct Foo {}
+/// This is different from [`foo()`]
+macro_rules! foo {
+  () => {}
+}
+```
 
-fn Foo() {}
+## Warnings, re-exports, and scoping
+
+Links are resolved in the scope of the module where the item is defined, even
+when the item is re-exported. If a link from another crate fails to resolve, no
+warning is given.
+
+When re-exporting an item, rustdoc allows adding additional documentation to it.
+That additional documentation will be resolved in the scope of the re-export, not
+the original, allowing you to link to items in the new crate. The new links
+will still give a warning if they fail to resolve.
+
+```rust
+/// See also [foo()]
+pub use std::process::Command;
+
+pub fn foo() {}
 ```
 
-Note: Because of how `macro_rules!` macros are scoped in Rust, the intra-doc links of a `macro_rules!` macro will be resolved [relative to the crate root][#72243], as opposed to the module it is defined in.
+This is especially useful for proc-macros, which must always be defined in their own dedicated crate.
+
+Note: Because of how `macro_rules!` macros are scoped in Rust, the intra-doc links of a
+`macro_rules!` macro will be resolved [relative to the crate root][#72243], as opposed to the
+module it is defined in.
+
+If links do not look 'sufficiently like' an intra-doc link, they will be ignored and no warning
+will be given, even if the link fails to resolve. For example, any link containing `/` or `[]`
+characters will be ignored. You can see the full criteria for 'sufficiently like' in [the source
+code].
 
 [#72243]: https://github.com/rust-lang/rust/issues/72243
+[the source code]: https://github.com/rust-lang/rust/blob/34628e5b533d35840b61c5db0665cf7633ed3c5a/src/librustdoc/passes/collect_intra_doc_links.rs#L982