Rustdoc: pub useing and/or globbing a submodule containing a pub macro (Macros 2.0) does not document the macro

[bstrie]

Rustdoc will properly generate the documentation for a Macros-2.0 macro when that macro is defined in a directly-exported submodule, e.g. pub mod foo { pub macro bar(). But if the module is not directly exported (pub mod foo {) but indirectly exported (pub use foo;) then the macro no longer exists in the documentation: the module documentation for mod foo will not mention it, and no page for the macro will be generated at all. The same problem occurs if a macro is exported via pub use foo::*.

Note that these are not problems with name resolution itself: Rust code will resolve the exported macro properly, the docs merely don't show it.

Example:

#![feature(decl_macro)]

mod outer {
    /// I am module documentation
    pub mod inner {
        /// I am macro documentation
        pub macro some_macro() {}

        /// I am struct documentation
        pub struct SomeStruct;
    }
}

// GOOD: this shows up properly in the top-level crate docs
pub use outer::inner::SomeStruct;

// GOOD: this shows up properly in the top-level crate docs
pub use outer::inner::some_macro;

// BAD: the `inner` module-level documentation shows the struct, but not the macro.
// If `outer` did not exist and `inner` were instead directly exported,
// then both items show up as expected.
pub use outer::inner;

(In the above example even though some_macro is not listed in the docs for inner, the docs page for some_macro will still be generated because of the explicit pub use outer::inner::some_macro; if this line is removed then that page will also vanish.)

Presumably this is a descendant of #74355 , where Macros-2.0 were not being documented at the correct paths. The fix for that issue landed in #77862 , although the fix itself appears to be regarded as a deplorable hack, and presumably the fix for this issue should not attempt to further hack the hack and instead make Macros 2.0 Just Work with Rustdoc.

[bstrie]

From Zulip:

Basically what's going on is that rustdoc is trying to reconstruct the privacy information after the fact. Rustc_resolve should just do that itself instead of giving rustdoc wrong information.

[jyn514]

Here is the proper fix I mentioned: #79396 (comment)

[jyn514]

See also #73754, which has the same root cause.

[inquisitivecrystal]

This should get fixed as part of #87406.