talk about intra-links

1 files changed, 45 insertions, 0 deletions

diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
index 8dbd0aa9a9a..08cceff0e70 100644
--- a/src/doc/rustdoc/src/unstable-features.md
+++ b/src/doc/rustdoc/src/unstable-features.md
@@ -31,3 +31,48 @@ future.
 
 Attempting to use these error numbers on stable will result in the code sample being interpreted as
 plain text.
+
+## Linking to items by type
+
+As designed in [RFC 1946], Rustdoc can parse paths to items when you use them as links. To resolve
+these type names, it uses the items currently in-scope, either by declaration or by `use` statement.
+For modules, the "active scope" depends on whether the documentation is written outside the module
+(as `///` comments on the `mod` statement) or inside the module (at `//!` comments inside the file
+or block). For all other items, it uses the enclosing module's scope.
+
+[RFC 1946]: https://github.com/rust-lang/rfcs/pull/1946
+
+For example, in the following code:
+
+```rust
+/// Does the thing.
+pub fn do_the_thing(_: SomeType) {
+	println!("Let's do the thing!");
+}
+
+/// Token you use to [`do_the_thing`].
+pub struct SomeType;
+```
+
+The link to ``[`do_the_thing`]`` in `SomeType`'s docs will properly link to the page for `fn
+do_the_thing`. Note that here, rustdoc will insert the link target for you, but manually writing the
+target out also works:
+
+```rust
+pub mod some_module {
+	/// Token you use to do the thing.
+	pub struct SomeStruct;
+}
+
+/// Does the thing. Requires one [`SomeStruct`] for the thing to work.
+///
+/// [`SomeStruct`]: some_module::SomeStruct
+pub fn do_the_thing(_: some_module::SomeStruct) {
+	println!("Let's do the thing!");
+}
+```
+
+For more details, check out [the RFC][RFC 1946], and see [the tracking issue][43466] for more
+information about what parts of the feature are available.
+
+[43466]: https://github.com/rust-lang/rust/issues/43466