From 058b72e5492151ece3a13d0c744402084455eb4b Mon Sep 17 00:00:00 2001
From: Manish Goregaokar <manishsmail@gmail.com>
Date: Sat, 27 Jun 2020 12:12:55 -0700
Subject: [PATCH 1/2] Add docs for intra-doc-links

---
 src/doc/rustdoc/src/SUMMARY.md         |  1 +
 src/doc/rustdoc/src/intra-doc-links.md | 59 ++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 src/doc/rustdoc/src/intra-doc-links.md

diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md
index f982863e67b94..1f38ab9c835e3 100644
--- a/src/doc/rustdoc/src/SUMMARY.md
+++ b/src/doc/rustdoc/src/SUMMARY.md
@@ -7,5 +7,6 @@
 - [Documentation tests](documentation-tests.md)
 - [Lints](lints.md)
 - [Passes](passes.md)
+- [Intra-doc links](intra-doc-links.md)
 - [Advanced Features](advanced-features.md)
 - [Unstable features](unstable-features.md)
diff --git a/src/doc/rustdoc/src/intra-doc-links.md b/src/doc/rustdoc/src/intra-doc-links.md
new file mode 100644
index 0000000000000..d203978111547
--- /dev/null
+++ b/src/doc/rustdoc/src/intra-doc-links.md
@@ -0,0 +1,59 @@
+# Intra-doc links
+
+_This feature is currently nightly-only_
+
+Rustdoc is capable of directly linking to other rustdoc pages in Markdown documentation using the path of item as a link.
+
+For example, in the following code all of the links will link to the rustdoc page for `Bar`:
+
+```rust
+
+/// This struct is not [Bar]
+pub struct Foo1;
+
+/// This struct is also not [bar](Bar)
+pub struct Foo2;
+
+/// This struct is also not [bar][b]
+///
+/// [b]: Bar
+pub struct Foo3;
+
+/// This struct is also not [`Bar`]
+pub struct Foo4;
+
+pub struct Bar;
+```
+
+You can refer to anything in scope, and use paths, including `Self`. You may also use `foo()` and `foo!()` to refer to methods/functions and macros respectively.
+
+```rust,edition2018
+use std::sync::mpsc::Receiver;
+
+/// This is an version of [`Receiver`], with support for [`std::future`].
+///
+/// You can obtain a [`std::future::Future`] by calling [`Self::recv()`].
+pub struct AsyncReceiver<T> {
+    sender: Receiver<T>
+}
+
+impl<T> AsyncReceiver<T> {
+    pub async fn recv() -> T {
+        unimplemented!()
+    }
+}
+```
+
+Paths in Rust have three namespaces: type, value, and macro. Items from these namespaces are allowed to overlap. 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@`, `function@`, `mod@`, `fn@`, `module@`, `method@` , `macro@`, or `derive@`:
+
+```rust
+/// See also: [`Foo`](struct@Foo)
+struct Bar;
+
+/// This is different from [`Foo`](fn@Foo)
+struct Foo {}
+
+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, as opposed to the module it is defined in.

From 8936846c1b9014535c14738337c311315dd1b33a Mon Sep 17 00:00:00 2001
From: Manish Goregaokar <manishsmail@gmail.com>
Date: Thu, 9 Jul 2020 08:31:44 -0700
Subject: [PATCH 2/2] Update src/doc/rustdoc/src/intra-doc-links.md

---
 src/doc/rustdoc/src/intra-doc-links.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/doc/rustdoc/src/intra-doc-links.md b/src/doc/rustdoc/src/intra-doc-links.md
index d203978111547..a0781e2e7690f 100644
--- a/src/doc/rustdoc/src/intra-doc-links.md
+++ b/src/doc/rustdoc/src/intra-doc-links.md
@@ -7,7 +7,6 @@ Rustdoc is capable of directly linking to other rustdoc pages in Markdown docume
 For example, in the following code all of the links will link to the rustdoc page for `Bar`:
 
 ```rust
-
 /// This struct is not [Bar]
 pub struct Foo1;