From 2a98409634ec38547d03512898192b5bdce15f3d Mon Sep 17 00:00:00 2001
From: Manish Goregaokar <manishsmail@gmail.com>
Date: Wed, 29 Jul 2020 15:18:37 -0700
Subject: [PATCH] Fill out docs on intra-doc resolution failure lint

---
 src/doc/rustdoc/src/lints.md | 43 ++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
index 8e2869fef553e..7c47f74b3c118 100644
--- a/src/doc/rustdoc/src/lints.md
+++ b/src/doc/rustdoc/src/lints.md
@@ -13,18 +13,53 @@ Here is the list of the lints provided by `rustdoc`:
 
 ## broken_intra_doc_links
 
-This lint **warns by default** and is **nightly-only**. This lint detects when
-an intra-doc link fails to get resolved. For example:
+This lint **warns by default**. This lint detects when an [intra-doc link] fails to get resolved. For example:
+
+ [intra-doc link]: linking-to-items-by-name.html
 
 ```rust
-/// I want to link to [`Inexistent`] but it doesn't exist!
+/// I want to link to [`Nonexistent`] but it doesn't exist!
 pub fn foo() {}
 ```
 
 You'll get a warning saying:
 
 ```text
-error: `[`Inexistent`]` cannot be resolved, ignoring it...
+warning: `[Nonexistent]` cannot be resolved, ignoring it.
+ --> test.rs:1:24
+  |
+1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
+  |                        ^^^^^^^^^^^^^ cannot be resolved, ignoring
+```
+
+It will also warn when there is an ambiguity and suggest how to disambiguate:
+
+```rust
+/// [`Foo`]
+pub fn function() {}
+
+pub enum Foo {}
+
+pub fn Foo(){}
+```
+
+```text
+warning: `Foo` is both an enum and a function
+ --> test.rs:1:6
+  |
+1 | /// [`Foo`]
+  |      ^^^^^ ambiguous link
+  |
+  = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
+help: to link to the enum, prefix with the item type
+  |
+1 | /// [`enum@Foo`]
+  |      ^^^^^^^^^^
+help: to link to the function, add parentheses
+  |
+1 | /// [`Foo()`]
+  |      ^^^^^^^
+
 ```
 
 ## missing_docs