pub macro defined in submodule is shown at the wrong path

[RalfJung]

rustdoc is showing the raw_mut macro at the wrong path in libcore: https://doc.rust-lang.org/nightly/core/macro.raw_mut.html says core::raw_mut but really it is core::ptr::raw_mut (and the same goes for core::ptr::raw_const). Looks like pub macro is not handled correctly?

Cc @rust-lang/rustdoc

[petrochenkov]

cc #63268

[GuillaumeGomez]

When a macro is marked as reexported, you can use it directly from the "top", so in this regard, isn't it the expected behavior?

[RalfJung]

AFAIK that is not true for macro macros, just for macro_rules! macros.

[RalfJung]

Note that there is no #[macro_export] here. This macro is exported via pub, like normal items (functions, structs, ...).

[RalfJung]

Code example:

#![feature(raw_ref_macros)]

fn main() {
    let mut x = 5;
    // This works.
    let xptr = core::ptr::raw_const!(x);
    // This does not.
    let xptr = core::raw_const!(x);
}

So I think there is definitely a rustdoc bug here. The path it shows does not work.

[GuillaumeGomez]

Oh I see. Indeed, it's a bug.

[yoshuawuyts]

Not sure if helpful, but the way we got public exports to work in rustdoc in async-std was by creating a separate crate (async-macros), and then re-exporting from from the main crate. This enabled us to render async_std::task::ready! in rustdoc.

This issue will also affect the upcoming core::task::ready! PR.

[RalfJung]

@GuillaumeGomez how hard is it to fix this problem, and what does the rustdoc team's prioritization for this look like? We'd like to stabilize #73394, and I am not sure if we want to stabilize this while its docs are rendered incorrectly.

[GuillaumeGomez]

Sorry but no idea. I don't have much time lately so maybe someone else from the @rust-lang/rustdoc will give it a try? Otherwise I'll try to fix it as soon as I have time.

[Manishearth]

Yeah so the problem here is that we have TypeKind::Macro which forces all macros to live at the root.

Given a Def or a Res, how do I tell if a macro is MBE or a newstyle macro?

(There's a possibility that our current code actually handles this correctly already and we need to remove the special case for TypeKind::Macro)

[Manishearth]

Okay so here are the two offending bits of code:

rust/src/librustdoc/visit_ast.rs

Lines 75 to 77 in ac48e62

	module
	.macros
	.extend(krate.exported_macros.iter().map(|def| self.visit_local_macro(def, None)));

rust/src/librustdoc/clean/inline.rs

Lines 175 to 179 in ac48e62

	let fqn = if let clean::TypeKind::Macro = kind {
	vec![crate_name, relative.last().expect("relative was empty")]
	} else {
	once(crate_name).chain(relative).collect()
	};

The latter is more about linking to these items rather than rendering them.

So the problem is that by the time stuff gets to rustdoc, we're looking at the HIR and the two kinds of macros are squashed together on hir::Crate::exported_macros. The newstyle macros are not a variant of hir::Item at all, they disappear from the HIR tree at that point and only exist as an array on the crate.

It would be nice if MBEs stayed on krate and newstyle macros were actually Items or at least stored separately on the module. We could handle these as we see their containing module, but that seems prone to issues when there are reexports and private modules in the mix.

I think having newstyle macros live on hir::Crate rather than hir::Mod is a mistake.

[Manishearth]

An option to do this purely in rustdoc would be to check the def_path and insert it in the appropriate modules after the fact, however this is kinda icky and i don't think this will be the last tooling problem encountered by newstyle macros living at the crate root in HIR.

[RalfJung]

@petrochenkov will probably know best how to interpret this information; somehow macro name resolution also has to work with this, after all.

[Manishearth]

I don't think name resolution actually operates on the hir that way. But yeah, worth letting him answer.

[jyn514]

The newstyle macros are not a variant of hir::Item at all, they disappear from the HIR tree at that point and only exist as an array on the crate.

I think you can recover the module they came from using the HirId and calling parent_module on it.

[jyn514]

You can tell whether it's a macro_rules macro or a pub macro by looking at MacroDef.macro_rules.