Description
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.