rust-lang/rust

rustdoc prioritises documenting reexports from the type namespace

Ryman opened this issue · 0 comments

Ryman commented

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.