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 prioritises documenting reexports from the type namespace #34843

Closed
Ryman opened this issue Jul 16, 2016 · 0 comments · Fixed by #51425
Closed

rustdoc prioritises documenting reexports from the type namespace #34843

Ryman opened this issue Jul 16, 2016 · 0 comments · Fixed by #51425
Assignees
Labels
C-bug Category: This is a bug. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@Ryman
Copy link
Contributor

Ryman commented Jul 16, 2016

If there's multiple items referred to by a reexport, rustdoc seems to only document the one in the type namespace.

pub use nested::sync;

mod nested {
    /// This shows up in docs
    pub mod sync {
        /// This shows up in docs
        pub fn inner() {
            println!("Hello from: {}", module_path!());
        }
    }

    /// This doesn't show up in docs
    pub fn sync() {
        println!("Hello from: {}", module_path!());
    }

    // This is denied by the compiler as the module is already defined,
    // but if it wasn't then this too would be documented instead of the function.
    // pub struct sync { a: usize }
}

The example main.rs below shows that resolve allows users to access sync in both capacities, so rustdoc should probably document both instances:

extern crate module_name_shadowing;

use module_name_shadowing::sync; // refers to sync as function
use module_name_shadowing::sync::inner; // refers to sync as module

fn main() {
    sync(); // ok - refers to sync function
    inner(); // ok - refers to sync::inner
    sync::inner(); // ok - refers to sync as a module
}

Related issue (it's about globs): #31337 (comment)
An example in the wild: mioco had to rename its sync function to offload due to it not appearing in the docs due to a sync module.

@Mark-Simulacrum Mark-Simulacrum added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label May 7, 2017
@frewsxcv frewsxcv added the T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. label May 18, 2017
@Mark-Simulacrum Mark-Simulacrum added the C-bug Category: This is a bug. label Jul 25, 2017
kennytm added a commit to kennytm/rust that referenced this issue May 24, 2018
… r=ollie27

 rustdoc: hide macro export statements from docs

As mentioned in rust-lang#50647, rustdoc now prints both the import statement and the macro itself when re-exporting macros. This is a stopgap solution to clean up the std docs and get something small backported into beta.

What this does: When rustdoc finds an export statement for a macro, instead of printing the export and bailing, now it will instead hide the export and bail. Until we can solve rust-lang#34843 or have a better way to find the attributes on an export statement when inlining macros, this will at least match the current behavior and clean up the re-export statements from the docs.
@QuietMisdreavus QuietMisdreavus self-assigned this Jun 4, 2018
bors added a commit that referenced this issue Jun 17, 2018
…=petrochenkov

refactor: create multiple HIR items for imports

When lowering `use` statements into HIR, they get a `Def` of the thing they're pointing at. This is great for things that need to know what was just pulled into scope. However, this is a bit misleading, because a `use` statement can pull things from multiple namespaces if their names collide. This is a problem for rustdoc, because if there are a module and a function with the same name (for example) then it will only document the module import, because that's that the lowered `use` statement points to.

The current version of this PR does the following:

* Whenever the resolver comes across a `use` statement, it loads the definitions into a new `import_map` instead of the existing `def_map`. This keeps the resolutions per-namespace so that all the target definitions are available.
* When lowering `use` statements, it looks up the resolutions in the `import_map` and creates multiple `Item`s if there is more than one resolution.
* To ensure the `NodeId`s are properly tracked in the lowered module, they need to be created in the AST, and pulled out as needed if multiple resolutions are available.

Fixes #34843
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-bug Category: This is a bug. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. 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.

4 participants