Rollup merge of #80874 - jyn514:intra-doc-docs, r=Manishearth

Update intra-doc link documentation to match the implementation

r? `@Manishearth`
cc `@camelid` `@m-ou-se`

Relevant PRs:
- https://github.com/rust-lang/rust/pull/74489
- https://github.com/rust-lang/rust/pull/80181
- https://github.com/rust-lang/rust/pull/76078
- https://github.com/rust-lang/rust/pull/77519
- https://github.com/rust-lang/rust/pull/73101

Relevant issues:
- https://github.com/rust-lang/rust/issues/78800
- https://github.com/rust-lang/rust/issues/77200
- https://github.com/rust-lang/rust/issues/77199 / https://github.com/rust-lang/rust/issues/54191/

I haven't documented things that I consider 'just bugs', like https://github.com/rust-lang/rust/issues/77732, but I have documented features that aren't implemented, like https://github.com/rust-lang/rust/issues/78800.

1 files changed, 62 insertions, 13 deletions

diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md
index 76e04398530..6ca1d1153b4 100644
--- a/src/doc/rustdoc/src/linking-to-items-by-name.md
+++ b/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,20 @@ pub struct Foo4;
 pub struct Bar;
 ```
 
+Unlike normal Markdown, `[bar][Bar]` syntax is also supported without needing a
+`[Bar]: ...` reference link.
+
 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 all primitives listed in
+[the standard library documentation](../std/index.html#primitives).
+
+[#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 +62,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 +71,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 suggest a disambiguator.
 
 ```rust
 /// See also: [`Foo`](struct@Foo)
@@ -76,19 +87,57 @@ struct Foo {}
 fn Foo() {}
 ```
 
+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.
+
+```rust,edition2018
+mod inner {
+    /// Link to [f()]
+    pub struct S;
+    pub fn f() {}
+}
+pub use inner::S; // the link to `f` will still resolve correctly
 ```
 
-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.
+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() {}
+```
+
+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.
 
 [#72243]: https://github.com/rust-lang/rust/issues/72243