Improve rustdoc error for failed intra-doc link resolution

The previous error was confusing since it made it sound like you can't
link to items that are defined outside the current module.

Also suggested importing the item.

8 files changed, 102 insertions, 58 deletions

diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs
index cf94ea384fd..632e6c9f91c 100644
--- a/src/librustdoc/passes/collect_intra_doc_links.rs
+++ b/src/librustdoc/passes/collect_intra_doc_links.rs
@@ -1575,17 +1575,17 @@ fn resolution_failure(
                         _ => None,
                     };
                     // See if this was a module: `[path]` or `[std::io::nope]`
-                    if let Some(module) = last_found_module {
-                        let module_name = collector.cx.tcx.item_name(module);
+                    if let Some(_module) = last_found_module {
                         let note = format!(
-                            "the module `{}` contains no item named `{}`",
-                            module_name, unresolved
+                            "there is no item named `{}` in scope",
+                            unresolved
                         );
                         if let Some(span) = sp {
                             diag.span_label(span, &note);
                         } else {
                             diag.note(&note);
                         }
+                        diag.help(&format!("did you mean to import `{}`?", unresolved));
                         // If the link has `::` in it, assume it was meant to be an intra-doc link.
                         // Otherwise, the `[]` might be unrelated.
                         // FIXME: don't show this for autolinks (`<>`), `()` style links, or reference links
diff --git a/src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr b/src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr
index 33260fa0e1e..96b805dbc82 100644
--- a/src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr
+++ b/src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr
@@ -2,13 +2,14 @@ error: unresolved link to `v2`
   --> $DIR/deny-intra-link-resolution-failure.rs:3:6
    |
 LL | /// [v2]
-   |      ^^ the module `deny_intra_link_resolution_failure` contains no item named `v2`
+   |      ^^ there is no item named `v2` in scope
    |
 note: the lint level is defined here
   --> $DIR/deny-intra-link-resolution-failure.rs:1:9
    |
 LL | #![deny(broken_intra_doc_links)]
    |         ^^^^^^^^^^^^^^^^^^^^^^
+   = help: did you mean to import `v2`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to previous error
diff --git a/src/test/rustdoc-ui/intra-link-errors.rs b/src/test/rustdoc-ui/intra-link-errors.rs
index 0278caf3087..babcc3c43b4 100644
--- a/src/test/rustdoc-ui/intra-link-errors.rs
+++ b/src/test/rustdoc-ui/intra-link-errors.rs
@@ -6,23 +6,28 @@
 
 /// [path::to::nonexistent::module]
 //~^ ERROR unresolved link
-//~| NOTE `intra_link_errors` contains no item named `path`
+//~| NOTE there is no item named `path` in scope
+//~| HELP did you mean to import `path`?
 
 /// [path::to::nonexistent::macro!]
 //~^ ERROR unresolved link
-//~| NOTE `intra_link_errors` contains no item named `path`
+//~| NOTE there is no item named `path` in scope
+//~| HELP did you mean to import `path`?
 
 /// [type@path::to::nonexistent::type]
 //~^ ERROR unresolved link
-//~| NOTE `intra_link_errors` contains no item named `path`
+//~| NOTE there is no item named `path` in scope
+//~| HELP did you mean to import `path`?
 
 /// [std::io::not::here]
 //~^ ERROR unresolved link
-//~| NOTE `io` contains no item named `not`
+//~| NOTE there is no item named `not` in scope
+//~| HELP did you mean to import `not`?
 
 /// [type@std::io::not::here]
 //~^ ERROR unresolved link
-//~| NOTE `io` contains no item named `not`
+//~| NOTE there is no item named `not` in scope
+//~| HELP did you mean to import `not`?
 
 /// [std::io::Error::x]
 //~^ ERROR unresolved link
diff --git a/src/test/rustdoc-ui/intra-link-errors.stderr b/src/test/rustdoc-ui/intra-link-errors.stderr
index b63f799535a..f9af1a9fb93 100644
--- a/src/test/rustdoc-ui/intra-link-errors.stderr
+++ b/src/test/rustdoc-ui/intra-link-errors.stderr
@@ -2,94 +2,103 @@ error: unresolved link to `path::to::nonexistent::module`
   --> $DIR/intra-link-errors.rs:7:6
    |
 LL | /// [path::to::nonexistent::module]
-   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the module `intra_link_errors` contains no item named `path`
+   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ there is no item named `path` in scope
    |
 note: the lint level is defined here
   --> $DIR/intra-link-errors.rs:1:9
    |
 LL | #![deny(broken_intra_doc_links)]
    |         ^^^^^^^^^^^^^^^^^^^^^^
+   = help: did you mean to import `path`?
 
 error: unresolved link to `path::to::nonexistent::macro`
-  --> $DIR/intra-link-errors.rs:11:6
+  --> $DIR/intra-link-errors.rs:12:6
    |
 LL | /// [path::to::nonexistent::macro!]
-   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the module `intra_link_errors` contains no item named `path`
+   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ there is no item named `path` in scope
+   |
+   = help: did you mean to import `path`?
 
 error: unresolved link to `path::to::nonexistent::type`
-  --> $DIR/intra-link-errors.rs:15:6
+  --> $DIR/intra-link-errors.rs:17:6
    |
 LL | /// [type@path::to::nonexistent::type]
-   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the module `intra_link_errors` contains no item named `path`
+   |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ there is no item named `path` in scope
+   |
+   = help: did you mean to import `path`?
 
 error: unresolved link to `std::io::not::here`
-  --> $DIR/intra-link-errors.rs:19:6
+  --> $DIR/intra-link-errors.rs:22:6
    |
 LL | /// [std::io::not::here]
-   |      ^^^^^^^^^^^^^^^^^^ the module `io` contains no item named `not`
+   |      ^^^^^^^^^^^^^^^^^^ there is no item named `not` in scope
+   |
+   = help: did you mean to import `not`?
 
 error: unresolved link to `std::io::not::here`
-  --> $DIR/intra-link-errors.rs:23:6
+  --> $DIR/intra-link-errors.rs:27:6
    |
 LL | /// [type@std::io::not::here]
-   |      ^^^^^^^^^^^^^^^^^^^^^^^ the module `io` contains no item named `not`
+   |      ^^^^^^^^^^^^^^^^^^^^^^^ there is no item named `not` in scope
+   |
+   = help: did you mean to import `not`?
 
 error: unresolved link to `std::io::Error::x`
-  --> $DIR/intra-link-errors.rs:27:6
+  --> $DIR/intra-link-errors.rs:32:6
    |
 LL | /// [std::io::Error::x]
    |      ^^^^^^^^^^^^^^^^^ the struct `Error` has no field or associated item named `x`
 
 error: unresolved link to `std::io::ErrorKind::x`
-  --> $DIR/intra-link-errors.rs:31:6
+  --> $DIR/intra-link-errors.rs:36:6
    |
 LL | /// [std::io::ErrorKind::x]
    |      ^^^^^^^^^^^^^^^^^^^^^ the enum `ErrorKind` has no variant or associated item named `x`
 
 error: unresolved link to `f::A`
-  --> $DIR/intra-link-errors.rs:35:6
+  --> $DIR/intra-link-errors.rs:40:6
    |
 LL | /// [f::A]
    |      ^^^^ `f` is a function, not a module or type, and cannot have associated items
 
 error: unresolved link to `f::A`
-  --> $DIR/intra-link-errors.rs:39:6
+  --> $DIR/intra-link-errors.rs:44:6
    |
 LL | /// [f::A!]
    |      ^^^^^ `f` is a function, not a module or type, and cannot have associated items
 
 error: unresolved link to `S::A`
-  --> $DIR/intra-link-errors.rs:43:6
+  --> $DIR/intra-link-errors.rs:48:6
    |
 LL | /// [S::A]
    |      ^^^^ the struct `S` has no field or associated item named `A`
 
 error: unresolved link to `S::fmt`
-  --> $DIR/intra-link-errors.rs:47:6
+  --> $DIR/intra-link-errors.rs:52:6
    |
 LL | /// [S::fmt]
    |      ^^^^^^ the struct `S` has no field or associated item named `fmt`
 
 error: unresolved link to `E::D`
-  --> $DIR/intra-link-errors.rs:51:6
+  --> $DIR/intra-link-errors.rs:56:6
    |
 LL | /// [E::D]
    |      ^^^^ the enum `E` has no variant or associated item named `D`
 
 error: unresolved link to `u8::not_found`
-  --> $DIR/intra-link-errors.rs:55:6
+  --> $DIR/intra-link-errors.rs:60:6
    |
 LL | /// [u8::not_found]
    |      ^^^^^^^^^^^^^ the builtin type `u8` has no associated item named `not_found`
 
 error: unresolved link to `std::primitive::u8::not_found`
-  --> $DIR/intra-link-errors.rs:59:6
+  --> $DIR/intra-link-errors.rs:64:6
    |
 LL | /// [std::primitive::u8::not_found]
    |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the builtin type `u8` has no associated item named `not_found`
 
 error: unresolved link to `Vec::into_iter`
-  --> $DIR/intra-link-errors.rs:63:6
+  --> $DIR/intra-link-errors.rs:68:6
    |
 LL | /// [type@Vec::into_iter]
    |      ^^^^^^^^^^^^^^^^^^^
@@ -98,7 +107,7 @@ LL | /// [type@Vec::into_iter]
    |      help: to link to the associated function, add parentheses: `Vec::into_iter()`
 
 error: unresolved link to `S`
-  --> $DIR/intra-link-errors.rs:68:6
+  --> $DIR/intra-link-errors.rs:73:6
    |
 LL | /// [S!]
    |      ^^
@@ -107,7 +116,7 @@ LL | /// [S!]
    |      help: to link to the struct, prefix with `struct@`: `struct@S`
 
 error: unresolved link to `T::g`
-  --> $DIR/intra-link-errors.rs:86:6
+  --> $DIR/intra-link-errors.rs:91:6
    |
 LL | /// [type@T::g]
    |      ^^^^^^^^^
@@ -116,13 +125,13 @@ LL | /// [type@T::g]
    |      help: to link to the associated function, add parentheses: `T::g()`
 
 error: unresolved link to `T::h`
-  --> $DIR/intra-link-errors.rs:91:6
+  --> $DIR/intra-link-errors.rs:96:6
    |
 LL | /// [T::h!]
    |      ^^^^^ the trait `T` has no macro named `h`
 
 error: unresolved link to `S::h`
-  --> $DIR/intra-link-errors.rs:78:6
+  --> $DIR/intra-link-errors.rs:83:6
    |
 LL | /// [type@S::h]
    |      ^^^^^^^^^
@@ -131,7 +140,7 @@ LL | /// [type@S::h]
    |      help: to link to the associated function, add parentheses: `S::h()`
 
 error: unresolved link to `m`
-  --> $DIR/intra-link-errors.rs:98:6
+  --> $DIR/intra-link-errors.rs:103:6
    |
 LL | /// [m()]
    |      ^^^
diff --git a/src/test/rustdoc-ui/intra-link-span-ice-55723.stderr b/src/test/rustdoc-ui/intra-link-span-ice-55723.stderr
index d946aa93980..57061b6778c 100644
--- a/src/test/rustdoc-ui/intra-link-span-ice-55723.stderr
+++ b/src/test/rustdoc-ui/intra-link-span-ice-55723.stderr
@@ -2,13 +2,14 @@ error: unresolved link to `i`
   --> $DIR/intra-link-span-ice-55723.rs:9:10
    |
 LL | /// （arr[i]）
-   |           ^ the module `intra_link_span_ice_55723` contains no item named `i`
+   |           ^ there is no item named `i` in scope
    |
 note: the lint level is defined here
   --> $DIR/intra-link-span-ice-55723.rs:1:9
    |
 LL | #![deny(broken_intra_doc_links)]
    |         ^^^^^^^^^^^^^^^^^^^^^^
+   = help: did you mean to import `i`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to previous error
diff --git a/src/test/rustdoc-ui/intra-links-warning-crlf.stderr b/src/test/rustdoc-ui/intra-links-warning-crlf.stderr
index 76a2ac0c8cf..0c934e3bb08 100644
--- a/src/test/rustdoc-ui/intra-links-warning-crlf.stderr
+++ b/src/test/rustdoc-ui/intra-links-warning-crlf.stderr
@@ -2,33 +2,37 @@ warning: unresolved link to `error`
   --> $DIR/intra-links-warning-crlf.rs:7:6
    |
 LL | /// [error]
-   |      ^^^^^ the module `intra_links_warning_crlf` contains no item named `error`
+   |      ^^^^^ there is no item named `error` in scope
    |
    = note: `#[warn(broken_intra_doc_links)]` on by default
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error1`
   --> $DIR/intra-links-warning-crlf.rs:12:11
    |
 LL | /// docs [error1]
-   |           ^^^^^^ the module `intra_links_warning_crlf` contains no item named `error1`
+   |           ^^^^^^ there is no item named `error1` in scope
    |
+   = help: did you mean to import `error1`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error2`
   --> $DIR/intra-links-warning-crlf.rs:15:11
    |
 LL | /// docs [error2]
-   |           ^^^^^^ the module `intra_links_warning_crlf` contains no item named `error2`
+   |           ^^^^^^ there is no item named `error2` in scope
    |
+   = help: did you mean to import `error2`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
   --> $DIR/intra-links-warning-crlf.rs:23:20
    |
 LL |  * It also has an [error].
-   |                    ^^^^^ the module `intra_links_warning_crlf` contains no item named `error`
+   |                    ^^^^^ there is no item named `error` in scope
    |
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: 4 warnings emitted
diff --git a/src/test/rustdoc-ui/intra-links-warning.stderr b/src/test/rustdoc-ui/intra-links-warning.stderr
index 09db465df59..d64f62924d3 100644
--- a/src/test/rustdoc-ui/intra-links-warning.stderr
+++ b/src/test/rustdoc-ui/intra-links-warning.stderr
@@ -10,54 +10,67 @@ warning: unresolved link to `Bar::foo`
   --> $DIR/intra-links-warning.rs:3:35
    |
 LL |        //! Test with [Foo::baz], [Bar::foo], ...
-   |                                   ^^^^^^^^ the module `intra_links_warning` contains no item named `Bar`
+   |                                   ^^^^^^^^ there is no item named `Bar` in scope
+   |
+   = help: did you mean to import `Bar`?
 
 warning: unresolved link to `Uniooon::X`
   --> $DIR/intra-links-warning.rs:6:13
    |
 LL |      //! , [Uniooon::X] and [Qux::Z].
-   |             ^^^^^^^^^^ the module `intra_links_warning` contains no item named `Uniooon`
+   |             ^^^^^^^^^^ there is no item named `Uniooon` in scope
+   |
+   = help: did you mean to import `Uniooon`?
 
 warning: unresolved link to `Qux::Z`
   --> $DIR/intra-links-warning.rs:6:30
    |
 LL |      //! , [Uniooon::X] and [Qux::Z].
-   |                              ^^^^^^ the module `intra_links_warning` contains no item named `Qux`
+   |                              ^^^^^^ there is no item named `Qux` in scope
+   |
+   = help: did you mean to import `Qux`?
 
 warning: unresolved link to `Uniooon::X`
   --> $DIR/intra-links-warning.rs:10:14
    |
 LL |       //! , [Uniooon::X] and [Qux::Z].
-   |              ^^^^^^^^^^ the module `intra_links_warning` contains no item named `Uniooon`
+   |              ^^^^^^^^^^ there is no item named `Uniooon` in scope
+   |
+   = help: did you mean to import `Uniooon`?
 
 warning: unresolved link to `Qux::Z`
   --> $DIR/intra-links-warning.rs:10:31
    |
 LL |       //! , [Uniooon::X] and [Qux::Z].
-   |                               ^^^^^^ the module `intra_links_warning` contains no item named `Qux`
+   |                               ^^^^^^ there is no item named `Qux` in scope
+   |
+   = help: did you mean to import `Qux`?
 
 warning: unresolved link to `Qux:Y`
   --> $DIR/intra-links-warning.rs:14:13
    |
 LL |        /// [Qux:Y]
-   |             ^^^^^ the module `intra_links_warning` contains no item named `Qux:Y`
+   |             ^^^^^ there is no item named `Qux:Y` in scope
    |
+   = help: did you mean to import `Qux:Y`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
   --> $DIR/intra-links-warning.rs:58:30
    |
 LL |  * time to introduce a link [error]*/
-   |                              ^^^^^ the module `intra_links_warning` contains no item named `error`
+   |                              ^^^^^ there is no item named `error` in scope
    |
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
   --> $DIR/intra-links-warning.rs:64:30
    |
 LL |  * time to introduce a link [error]
-   |                              ^^^^^ the module `intra_links_warning` contains no item named `error`
+   |                              ^^^^^ there is no item named `error` in scope
    |
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
@@ -70,7 +83,8 @@ LL | #[doc = "single line [error]"]
            
            single line [error]
                         ^^^^^
-   = note: the module `intra_links_warning` contains no item named `error`
+   = note: there is no item named `error` in scope
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
@@ -83,7 +97,8 @@ LL | #[doc = "single line with \"escaping\" [error]"]
            
            single line with "escaping" [error]
                                         ^^^^^
-   = note: the module `intra_links_warning` contains no item named `error`
+   = note: there is no item named `error` in scope
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error`
@@ -98,47 +113,53 @@ LL | | /// [error]
            
            [error]
             ^^^^^
-   = note: the module `intra_links_warning` contains no item named `error`
+   = note: there is no item named `error` in scope
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error1`
   --> $DIR/intra-links-warning.rs:80:11
    |
 LL | /// docs [error1]
-   |           ^^^^^^ the module `intra_links_warning` contains no item named `error1`
+   |           ^^^^^^ there is no item named `error1` in scope
    |
+   = help: did you mean to import `error1`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `error2`
   --> $DIR/intra-links-warning.rs:82:11
    |
 LL | /// docs [error2]
-   |           ^^^^^^ the module `intra_links_warning` contains no item named `error2`
+   |           ^^^^^^ there is no item named `error2` in scope
    |
+   = help: did you mean to import `error2`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `BarA`
   --> $DIR/intra-links-warning.rs:21:10
    |
 LL | /// bar [BarA] bar
-   |          ^^^^ the module `intra_links_warning` contains no item named `BarA`
+   |          ^^^^ there is no item named `BarA` in scope
    |
+   = help: did you mean to import `BarA`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `BarB`
   --> $DIR/intra-links-warning.rs:27:9
    |
 LL |  * bar [BarB] bar
-   |         ^^^^ the module `intra_links_warning` contains no item named `BarB`
+   |         ^^^^ there is no item named `BarB` in scope
    |
+   = help: did you mean to import `BarB`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `BarC`
   --> $DIR/intra-links-warning.rs:34:6
    |
 LL | bar [BarC] bar
-   |      ^^^^ the module `intra_links_warning` contains no item named `BarC`
+   |      ^^^^ there is no item named `BarC` in scope
    |
+   = help: did you mean to import `BarC`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `BarD`
@@ -151,7 +172,8 @@ LL | #[doc = "Foo\nbar [BarD] bar\nbaz"]
            
            bar [BarD] bar
                 ^^^^
-   = note: the module `intra_links_warning` contains no item named `BarD`
+   = note: there is no item named `BarD` in scope
+   = help: did you mean to import `BarD`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: unresolved link to `BarF`
@@ -167,7 +189,8 @@ LL | f!("Foo\nbar [BarF] bar\nbaz");
            
            bar [BarF] bar
                 ^^^^
-   = note: the module `intra_links_warning` contains no item named `BarF`
+   = note: there is no item named `BarF` in scope
+   = help: did you mean to import `BarF`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this warning originates in a macro (in Nightly builds, run with -Z macro-backtrace for more info)
 
diff --git a/src/test/rustdoc-ui/lint-group.stderr b/src/test/rustdoc-ui/lint-group.stderr
index 4e9134ea469..1fe33b41167 100644
--- a/src/test/rustdoc-ui/lint-group.stderr
+++ b/src/test/rustdoc-ui/lint-group.stderr
@@ -32,7 +32,7 @@ error: unresolved link to `error`
   --> $DIR/lint-group.rs:9:29
    |
 LL | /// what up, let's make an [error]
-   |                             ^^^^^ the module `lint_group` contains no item named `error`
+   |                             ^^^^^ there is no item named `error` in scope
    |
 note: the lint level is defined here
   --> $DIR/lint-group.rs:7:9
@@ -40,6 +40,7 @@ note: the lint level is defined here
 LL | #![deny(rustdoc)]
    |         ^^^^^^^
    = note: `#[deny(broken_intra_doc_links)]` implied by `#[deny(rustdoc)]`
+   = help: did you mean to import `error`?
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to 3 previous errors