Rustdoc link with module@ does not link to the module

[dtolnay]

Starting with an ambiguous lib.rs:

pub mod x {}
pub fn x() {}

/// [x]
pub struct S;

rustdoc correctly reports the ambiguity and suggests the possible resolutions:

warning: `x` is both a module and a function
 --> src/lib.rs:4:6
  |
4 | /// [x]
  |      ^ ambiguous link
  |
  = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
help: to link to the module, prefix with the item type
  |
4 | /// [module@x]
  |      ^^^^^^^^
help: to link to the function, add parentheses
  |
4 | /// [x()]
  |      ^^^

In this case I want to link to the module so let's update lib.rs:

pub mod x {}
pub fn x() {}

/// [module@x]
pub struct S;

cargo doc accepts this without warnings but the generated html file contains:

<a href="../repro/fn.x.html" title="module@x">module@x</a>

I would expect [module@x] to link to the module x, not the function x.

Mentioning tracking issue: #43466

[dtolnay]

Workaround: leverage rustc's name resolution instead of rustdoc's. dtolnay/syn@ae1983c

pub mod x {}
pub fn x() {}

/// [module@x]
///
/// [module@x]: crate::rustdoc_workaround::x_module
pub struct S;

// https://github.com/rust-lang/rust/issues/62830
mod rustdoc_workaround {
    pub use crate::x::{self as x_module};
    //             ^^^^^^^^ no ambiguity with function
}

[jyn514]

This is coming directly from rustc_resolve, so I'm not sure how to fix it. Maybe @Manishearth has ideas? The issue is that currently we can only select between types, values, and macros, and modules count as all three so there's not a way to say 'only give me modules'. https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/enum.Namespace.html

[jyn514]

I think eventually we should switch rustdoc to using smart_resolve_path which has support for fine distinctions like this through PathSource. That would also fix #74207. But I have no idea how hard that would be.

[Manishearth]

Yeah I don't know either. I'm not sure how that overlap works in resolve. @eddyb might?

We could tweak the resolve resolution functions to force looking for modules.

[eddyb]

I don't know much about name resolution, you want @petrochenkov.

Only thing I know is that it should be possible to get a PerNs<Res> and then use whichever namespace you want from there at your discretion.

[Manishearth]

@eddyb the problem is that modules seem to be special and exist in all namespaces but also overlap. Do you have an idea of how that works?

[eddyb]

"Modules count as all three" sounds wrong? Modules live in the type namespace last I checked.

[Manishearth]

Oh! Maybe we should just switch modules to being a type then, I was under the impression they lvied in all namespaces

[Manishearth]

And yeah, seems like types cannot overlap with modules.

[jyn514]

Wait I'm confused - I thought functions are in the type namespace? Are they values instead?