Stream: rustdoc

Topic: macros 2.0


view this post on Zulip bstrie (Jul 18 2021 at 17:50):

@Joshua Nelson I seem to recall you saying that macros 2.0 support in rustdoc is less than ideal, and I'm having difficulty with it right now and I'm curious if my problem is already understood and/or something I could easily fix. Specifically when you define a macro in a submodule, and then you export that submodule via pub use, the macro definition does not show up in the generated docs. Non-macro items show up as expected, and the behavior doesn't manifest if the submodule is just directly exported via pub mod rather than via pub use.

view this post on Zulip bstrie (Jul 18 2021 at 17:51):

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;

view this post on Zulip bstrie (Jul 18 2021 at 17:54):

it's not a problem in name resolution itself; if you attempt to use the macro exported in such a way then it resolves successfully. it's just something with the docs

view this post on Zulip bstrie (Jul 18 2021 at 17:56):

what's worse is that not only is the macro not listed in the module-level docs, but if you remove that top-level export then the macro just plain doesn't exist at all in the docs, you can't search for it and its page doesn't get generated

view this post on Zulip bstrie (Jul 18 2021 at 18:04):

Looks like the same problem arises if you attempt to pub use with glob imports in any capacity, perhaps it's the same cause

view this post on Zulip Joshua Nelson (Jul 18 2021 at 18:11):

I personally am not willing to accept any fixes for the hack for macros 2.0, other than the proper fix of getting rid of it. If this affects things other than macros then it's worth opening an issue; I vaguely remember that rustdoc handles glob reexports wrong somehow, there's a closed PR a while back.

view this post on Zulip bstrie (Jul 18 2021 at 18:14):

is there a tracking issue for "doing macros 2.0 support properly"?

view this post on Zulip Joshua Nelson (Jul 18 2021 at 18:15):

I'm not sure. There are lots of comments by Petrochenkov, but they're scattered around various issues. Search for "exported_macros" (it needs to be removed completely for this to work properly)

view this post on Zulip Joshua Nelson (Jul 18 2021 at 18:16):

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.

view this post on Zulip Joshua Nelson (Jul 18 2021 at 18:18):

There's a writeup on the PR originally adding the hack I think

view this post on Zulip bstrie (Jul 18 2021 at 18:44):

I've filed an issue at https://github.com/rust-lang/rust/issues/87257


Last updated: Oct 11 2021 at 22:34 UTC