Rollup merge of #74528 - euclio:intra-link-errors, r=jyn514

refactor and reword intra-doc link errors

This commit refactors intra-doc link error reporting to deduplicate code
and decouple error construction from the type of error. This greatly
improves flexibility at each error construction site, while reducing the
complexity of the diagnostic creation.

This commit also rewords the diagnostics for clarity and style:

- Diagnostics should not end in periods.
- It's unnecessary to say "ignoring it". Since this is a warning by
  default, it's already clear that the link is ignored.

Author: Manishearth

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -1,15 +1,15 @@
-error: `[v2]` cannot be resolved, ignoring it.
+error: unresolved link to `v2`
   --> $DIR/deny-intra-link-resolution-failure.rs:3:6
    |
 LL | /// [v2]
-   |      ^^ cannot be resolved, ignoring
+   |      ^^ unresolved link
    |
 note: the lint level is defined here
   --> $DIR/deny-intra-link-resolution-failure.rs:1:9
    |
 LL | #![deny(intra_doc_link_resolution_failure)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to previous error
 

src/test/rustdoc-ui/deny-intra-link-resolution-failure.stderr

@@ -1,15 +1,15 @@
-error: `[TypeAlias::hoge]` cannot be resolved, ignoring it.
+error: unresolved link to `TypeAlias::hoge`
   --> $DIR/intra-doc-alias-ice.rs:5:30
    |
 LL | /// [broken cross-reference](TypeAlias::hoge)
-   |                              ^^^^^^^^^^^^^^^ cannot be resolved, ignoring
+   |                              ^^^^^^^^^^^^^^^ unresolved link
    |
 note: the lint level is defined here
   --> $DIR/intra-doc-alias-ice.rs:1:9
    |
 LL | #![deny(intra_doc_link_resolution_failure)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to previous error
 

src/test/rustdoc-ui/intra-doc-alias-ice.stderr

@@ -7,7 +7,7 @@
 /// ## For example:
 ///
 /// （arr[i]）
-//~^ ERROR `[i]` cannot be resolved, ignoring it.
+//~^ ERROR `i`
 pub fn test_ice() {
     unimplemented!();
 }

src/test/rustdoc-ui/intra-link-span-ice-55723.rs

@@ -1,15 +1,15 @@
-error: `[i]` cannot be resolved, ignoring it.
+error: unresolved link to `i`
   --> $DIR/intra-link-span-ice-55723.rs:9:10
    |
 LL | /// （arr[i]）
-   |           ^ cannot be resolved, ignoring
+   |           ^ unresolved link
    |
 note: the lint level is defined here
   --> $DIR/intra-link-span-ice-55723.rs:1:9
    |
 LL | #![deny(intra_doc_link_resolution_failure)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 error: aborting due to previous error
 

src/test/rustdoc-ui/intra-link-span-ice-55723.stderr

@@ -23,23 +23,23 @@ pub enum Enum {
 /// Like [Foo#hola].
 ///
 /// Or maybe [Foo::f#hola].
-//~^ ERROR `[Foo::f#hola]` has an issue with the link anchor.
+//~^ ERROR `Foo::f#hola` contains an anchor
 pub fn foo() {}
 
 /// Empty.
 ///
 /// Another anchor error: [hello#people#!].
-//~^ ERROR `[hello#people#!]` has an issue with the link anchor.
+//~^ ERROR `hello#people#!` contains multiple anchors
 pub fn bar() {}
 
 /// Empty?
 ///
 /// Damn enum's variants: [Enum::A#whatever].
-//~^ ERROR `[Enum::A#whatever]` has an issue with the link anchor.
+//~^ ERROR `Enum::A#whatever` contains an anchor
 pub fn enum_link() {}
 
 /// Primitives?
 ///
 /// [u32#hello]
-//~^ ERROR `[u32#hello]` has an issue with the link anchor.
+//~^ ERROR `u32#hello` contains an anchor
 pub fn x() {}

src/test/rustdoc-ui/intra-links-anchors.rs

@@ -1,32 +1,32 @@
-error: `[Foo::f#hola]` has an issue with the link anchor.
+error: `Foo::f#hola` contains an anchor, but links to struct fields are already anchored
   --> $DIR/intra-links-anchors.rs:25:15
    |
 LL | /// Or maybe [Foo::f#hola].
-   |               ^^^^^^^^^^^ struct fields cannot be followed by anchors
+   |               ^^^^^^^^^^^ contains invalid anchor
    |
 note: the lint level is defined here
   --> $DIR/intra-links-anchors.rs:1:9
    |
 LL | #![deny(intra_doc_link_resolution_failure)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-error: `[hello#people#!]` has an issue with the link anchor.
+error: `hello#people#!` contains multiple anchors
   --> $DIR/intra-links-anchors.rs:31:28
    |
 LL | /// Another anchor error: [hello#people#!].
-   |                            ^^^^^^^^^^^^^^ only one `#` is allowed in a link
+   |                            ^^^^^^^^^^^^^^ contains invalid anchor
 
-error: `[Enum::A#whatever]` has an issue with the link anchor.
+error: `Enum::A#whatever` contains an anchor, but links to enum variants are already anchored
   --> $DIR/intra-links-anchors.rs:37:28
    |
 LL | /// Damn enum's variants: [Enum::A#whatever].
-   |                            ^^^^^^^^^^^^^^^^ variants cannot be followed by anchors
+   |                            ^^^^^^^^^^^^^^^^ contains invalid anchor
 
-error: `[u32#hello]` has an issue with the link anchor.
+error: `u32#hello` contains an anchor, but links to primitive types are already anchored
   --> $DIR/intra-links-anchors.rs:43:6
    |
 LL | /// [u32#hello]
-   |      ^^^^^^^^^ primitive types cannot be followed by anchors
+   |      ^^^^^^^^^ contains invalid anchor
 
 error: aborting due to 4 previous errors
 

src/test/rustdoc-ui/intra-links-anchors.stderr

@@ -1,4 +1,4 @@
-warning: `[DontDocMe]` public documentation for `DocMe` links to a private item
+warning: public documentation for `DocMe` links to private item `DontDocMe`
   --> $DIR/intra-links-private.rs:6:11
    |
 LL | /// docs [DontDocMe]

src/test/rustdoc-ui/intra-links-private.public.stderr

@@ -4,7 +4,7 @@
 #![cfg_attr(private, deny(intra_doc_link_resolution_failure))]
 
 /// docs [DontDocMe]
-//[public]~^ WARNING `[DontDocMe]` public documentation for `DocMe` links to a private item
+//[public]~^ WARNING public documentation for `DocMe` links to private item `DontDocMe`
 // FIXME: for [private] we should also make sure the link was actually generated
 pub struct DocMe;
 struct DontDocMe;

src/test/rustdoc-ui/intra-links-private.rs

@@ -6,21 +6,21 @@
 
 /// [error]
 pub struct A;
-//~^^ WARNING `[error]` cannot be resolved
+//~^^ WARNING `error`
 
 ///
 /// docs [error1]
-//~^ WARNING `[error1]` cannot be resolved
+//~^ WARNING `error1`
 
 /// docs [error2]
 ///
 pub struct B;
-//~^^^ WARNING `[error2]` cannot be resolved
+//~^^^ WARNING `error2`
 
 /**
  * This is a multi-line comment.
  *
  * It also has an [error].
  */
 pub struct C;
-//~^^^ WARNING `[error]` cannot be resolved
+//~^^^ WARNING `error`

src/test/rustdoc-ui/intra-links-warning-crlf.rs

@@ -1,35 +1,35 @@
-warning: `[error]` cannot be resolved, ignoring it.
+warning: unresolved link to `error`
   --> $DIR/intra-links-warning-crlf.rs:7:6
    |
 LL | /// [error]
-   |      ^^^^^ cannot be resolved, ignoring
+   |      ^^^^^ unresolved link
    |
    = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
-warning: `[error1]` cannot be resolved, ignoring it.
+warning: unresolved link to `error1`
   --> $DIR/intra-links-warning-crlf.rs:12:11
    |
 LL | /// docs [error1]
-   |           ^^^^^^ cannot be resolved, ignoring
+   |           ^^^^^^ unresolved link
    |
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
-warning: `[error2]` cannot be resolved, ignoring it.
+warning: unresolved link to `error2`
   --> $DIR/intra-links-warning-crlf.rs:15:11
    |
 LL | /// docs [error2]
-   |           ^^^^^^ cannot be resolved, ignoring
+   |           ^^^^^^ unresolved link
    |
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
-warning: `[error]` cannot be resolved, ignoring it.
+warning: unresolved link to `error`
   --> $DIR/intra-links-warning-crlf.rs:23:20
    |
 LL |  * It also has an [error].
-   |                    ^^^^^ cannot be resolved, ignoring
+   |                    ^^^^^ unresolved link
    |
-   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
+   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
 
 warning: 4 warnings emitted
 

src/test/rustdoc-ui/intra-links-warning-crlf.stderr

@@ -1,37 +1,37 @@
 // check-pass
 
        //! Test with [Foo::baz], [Bar::foo], ...
-//~^ WARNING `[Foo::baz]` cannot be resolved
-//~| WARNING `[Bar::foo]` cannot be resolved
+//~^ WARNING `Foo::baz`
+//~| WARNING `Bar::foo`
      //! , [Uniooon::X] and [Qux::Z].
-//~^ WARNING `[Uniooon::X]` cannot be resolved
-//~| WARNING `[Qux::Z]` cannot be resolved
+//~^ WARNING `Uniooon::X`
+//~| WARNING `Qux::Z`
        //!
       //! , [Uniooon::X] and [Qux::Z].
-//~^ WARNING `[Uniooon::X]` cannot be resolved
-//~| WARNING `[Qux::Z]` cannot be resolved
+//~^ WARNING `Uniooon::X`
+//~| WARNING `Qux::Z`
 
        /// [Qux:Y]
-//~^ WARNING `[Qux:Y]` cannot be resolved
+//~^ WARNING `Qux:Y`
 pub struct Foo {
     pub bar: usize,
 }
 
 /// Foo
-/// bar [BarA] bar //~ WARNING `[BarA]` cannot be resolved
+/// bar [BarA] bar //~ WARNING `BarA`
 /// baz
 pub fn a() {}
 
 /**
  * Foo
- * bar [BarB] bar //~ WARNING `[BarB]` cannot be resolved
+ * bar [BarB] bar //~ WARNING `BarB`
  * baz
  */
 pub fn b() {}
 
 /** Foo
 
-bar [BarC] bar //~ WARNING `[BarC]` cannot be resolved
+bar [BarC] bar //~ WARNING `BarC`
 baz
 
     let bar_c_1 = 0;
@@ -42,43 +42,43 @@ baz
 */
 pub fn c() {}
 
-#[doc = "Foo\nbar [BarD] bar\nbaz"] //~ WARNING `[BarD]` cannot be resolved
+#[doc = "Foo\nbar [BarD] bar\nbaz"] //~ WARNING `BarD`
 pub fn d() {}
 
 macro_rules! f {
     ($f:expr) => {
-        #[doc = $f] //~ WARNING `[BarF]` cannot be resolved
+        #[doc = $f] //~ WARNING `BarF`
         pub fn f() {}
     }
 }
 f!("Foo\nbar [BarF] bar\nbaz");
 
 /** # for example,
  *
- * time to introduce a link [error]*/ //~ WARNING `[error]` cannot be resolved
+ * time to introduce a link [error]*/ //~ WARNING `error`
 pub struct A;
 
 /**
  * # for example,
  *
- * time to introduce a link [error] //~ WARNING `[error]` cannot be resolved
+ * time to introduce a link [error] //~ WARNING `error`
  */
 pub struct B;
 
-#[doc = "single line [error]"] //~ WARNING `[error]` cannot be resolved
+#[doc = "single line [error]"] //~ WARNING `error`
 pub struct C;
 
-#[doc = "single line with \"escaping\" [error]"] //~ WARNING `[error]` cannot be resolved
+#[doc = "single line with \"escaping\" [error]"] //~ WARNING `error`
 pub struct D;
 
-/// Item docs. //~ WARNING `[error]` cannot be resolved
+/// Item docs. //~ WARNING `error`
 #[doc="Hello there!"]
 /// [error]
 pub struct E;
 
 ///
-/// docs [error1] //~ WARNING `[error1]` cannot be resolved
+/// docs [error1] //~ WARNING `error1`
 
-/// docs [error2] //~ WARNING `[error2]` cannot be resolved
+/// docs [error2] //~ WARNING `error2`
 ///
 pub struct F;