Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc intra links: Module-level doc uses parent module's namespace instead of own #55364

Closed
crumblingstatue opened this issue Oct 25, 2018 · 2 comments · Fixed by #65857
Closed
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@crumblingstatue
Copy link
Contributor

pub mod sub {
    //! See either [foo] or [bar].

    /// See [bar]
    pub fn foo() {}
    /// See [foo]
    pub fn bar() {}
}
2 |     //! See either [foo] or [bar].
  |                     ^^^ cannot be resolved, ignoring

I don't know if this is an accidental regression, or an intentional change, but this used to resolve.

I argue that module-level docs should have the same namespace as the module they are referring to, since referring to the items of the documented module is much more common than referring to items in the parent module.

Ref #43466

@Nemo157
Copy link
Member

Nemo157 commented Oct 26, 2018

I definitely agree with the motivation.

One issue is what about outer-doc comments on a module?

/// See either [foo] or [bar].
pub mod sub {
    /// See [bar]
    pub fn foo() {}
    /// See [foo]
    pub fn bar() {}
}

I'm not sure if they're distinguishable to rustdoc, and also not sure whether they should have the same behaviour or resolve from the module in which they're actually written.

@memoryruins memoryruins added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Oct 29, 2018
@QuietMisdreavus QuietMisdreavus added the A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name label Nov 6, 2018
@Manishearth
Copy link
Member

They are distinguishable, I recall I knowingly skipped this when implementing this feature because it was tricky to get right and I wasn't sure which way we wanted it to work.

tmandry added a commit to tmandry/rust that referenced this issue Oct 31, 2019

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
…nisheart,GuillaumeGomez

rustdoc: Resolve module-level doc references more locally

Module level docs should resolve intra-doc links as locally as
possible.  As such, this commit alters the heuristic for finding
intra-doc links such that we attempt to resolve names mentioned
in *inner* documentation comments within the (sub-)module rather
that from the context of its parent.

I'm hoping that this fixes rust-lang#55364 though right now I'm not sure it's the right fix.

r? @GuillaumeGomez
@bors bors closed this as completed in 48a9f59 Nov 1, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants