Skip to content

Add item suggestions for broken intra doc links #74207

Open
@pickfire

Description

@pickfire
Contributor

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

Activity

jyn514

jyn514 commented on Jul 10, 2020

@jyn514
Member

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

jyn514 commented on Jul 10, 2020

@jyn514
Member

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

added
A-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by name
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Jul 10, 2020
jyn514

jyn514 commented on Jul 10, 2020

@jyn514
Member

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

jyn514 commented on Jul 10, 2020

@jyn514
Member

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

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

jyn514

jyn514 commented on Jul 10, 2020

@jyn514
Member

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.

changed the title [-]Diagnostic for intra-doc links[/-] [+]Add item suggestions for broken intra doc links[/+] on Jul 10, 2020
Manishearth

Manishearth commented on Jul 10, 2020

@Manishearth
Member

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

pickfire commented on Jul 10, 2020

@pickfire
ContributorAuthor

@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

jyn514 commented on Jul 10, 2020

@jyn514
Member

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

jyn514 commented on Jul 10, 2020

@jyn514
Member

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.

added
A-diagnosticsArea: Messages for errors, warnings, and lints
A-suggestion-diagnosticsArea: Suggestions generated by the compiler applied by `cargo fix`
on Aug 8, 2020
added a commit that references this issue on Aug 30, 2020

Auto merge of rust-lang#75176 - jyn514:impl-link, r=GuillaumeGomez,pe…

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-diagnosticsArea: Messages for errors, warnings, and lintsA-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameA-suggestion-diagnosticsArea: Suggestions generated by the compiler applied by `cargo fix`C-enhancementCategory: An issue proposing an enhancement or a PR with one.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @Manishearth@pickfire@jyn514@rustbot

        Issue actions

          Add item suggestions for broken intra doc links · Issue #74207 · rust-lang/rust