Open
Description
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
Metadata
Metadata
Assignees
Labels
Area: Messages for errors, warnings, and lintsArea: Intra-doc links, the ability to link to items in docs by nameArea: Suggestions generated by the compiler applied by `cargo fix`Category: An issue proposing an enhancement or a PR with one.Relevant to the rustdoc team, which will review and decide on the PR/issue.
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Activity
jyn514 commentedon Jul 10, 2020
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 commentedon Jul 10, 2020
@rustbot modify labels: T-rustdoc A-intra-doc-links C-enhancement
jyn514 commentedon Jul 10, 2020
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. Seeresolve_str_path_error
. We'd need to get theResolutionError
fromresolve_ast_path
, which has asuggestion
field. The comment onresolve_str_path_error
seems to indicate this might run into trouble with lifetimes.jyn514 commentedon Jul 10, 2020
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
I guess we could try suggesting everything? Better too much information than too little.
jyn514 commentedon Jul 10, 2020
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 theFailedToResolve
variant, which is not a borrow. So we can return that suggestion directly without having to worry about lifetimes.[-]Diagnostic for intra-doc links[/-][+]Add item suggestions for broken intra doc links[/+]Manishearth commentedon Jul 10, 2020
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 commentedon Jul 10, 2020
@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 commentedon Jul 10, 2020
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 commentedon Jul 10, 2020
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.[NOT USEFUL] Start working on rust-lang#74207
Auto merge of rust-lang#75176 - jyn514:impl-link, r=GuillaumeGomez,pe…
broken_intra_doc_links
triggers on link to private item #83049