Skip to content

rustdoc prioritises documenting reexports from the type namespace #34843

Closed
@Ryman

Description

@Ryman

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.

Metadata

Metadata

Labels

C-bugCategory: This is a bug.T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.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

Issue actions