Add item suggestions for broken intra doc links

[pickfire]

The diagnostics for intra-doc links could be improve to match the diagnostics available in rust.

Current error message

warning: `[extend]` cannot be resolved, ignoring it.
   --> src/vec.rs:704:45
    |
704 |     /// Note that this function is same as [`extend`] except that it is specialized to work with
    |                                             ^^^^^^^^ cannot be resolved, ignoring
    |
    = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
    = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

The diagnostics should suggest Self::extend(). Note that it should also handle path ambiguity unlike the current diagnostics with struct@, enum@ and others in the original RFC.

Original RFC: https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md
Tracking issue for intra-doc links: #43466

CC @QuietMisdreavus @Manishearth @jyn514

[jyn514]

FYI QuietMisdreavus is no longer an active member of the rustdoc team, so let's avoid pinging her unless we need something specific only she knows.

[jyn514]

@rustbot modify labels: T-rustdoc A-intra-doc-links C-enhancement

[jyn514]

This is non-trivial because we currently don't have any of the information that rustc_resolve has - we only know whether the type resolved or not. See resolve_str_path_error. We'd need to get the ResolutionError from resolve_ast_path, which has a suggestion field. The comment on resolve_str_path_error seems to indicate this might run into trouble with lifetimes.

[jyn514]

Additionally, most of the time we don't know the namespace of the item. So we don't know if we should use type suggestions, macro suggestions, or value suggestions. See

rust/src/librustdoc/passes/collect_intra_doc_links.rs

Line 703 in 08d3a74

// Try everything!

I guess we could try suggesting everything? Better too much information than too little.

[jyn514]

The comment on resolve_str_path_error seems to indicate this might run into trouble with lifetimes.

Oh! This is only an issue because ResolutionError can contain a variant that's a borrow (&'a). But the only thing rustdoc cares about is the FailedToResolve variant, which is not a borrow. So we can return that suggestion directly without having to worry about lifetimes.

[Manishearth]

An easy thing we could do is apply this suggestion for the "link to a method on the current Self type" case only, as a start. That's reasonably easier.

[pickfire]

@jyn514 Ah, sorry about pinging her, I didn't know she wasn't an active member. As well, can you please help to add E-hard label for this?

[jyn514]

I don't think this is actually an E-hard, I'm working on it now and I think it's doable in a day or so.

[jyn514]

Ugh this is not as simple as just returning the Suggestion, all the useful suggestions happen in https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/late/struct.LateResolutionVisitor.html#method.smart_resolve_report_errors which is a lot more complicated.