Rustdoc: pub useing and/or globbing a submodule containing a pub macro (Macros 2.0) does not document the macro · Issue #87257 · rust-lang/rust (original) (raw)

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.