rustdoc: doc(hidden) also hides re-exports

Code:

#[macro_use]
pub mod my_module {
    /// This is a simple macro.
    #[macro_export]
    #[doc(hidden)]
    macro_rules! foo {
        () => ();
    }

    /// This doc comment doesn't show up in rustdoc (there's just an ugly re-export).
    pub use crate::foo as bar;

    // And this re-export doesn't show up in rustdoc at all!
    #[doc(inline)]
    pub use crate::foo as baz;
}

Generated docs:

So what I want to do is create a macro inside my_module. I don't want it to show up in crate root - I want it only in this module.

Both of the re-exports above work just fine. However, in the generated docs, one of them has no docs and the other doesn't show up at all.

I'm surprised that #[doc(hidden)] is "recursive" - shouldn't it only hide foo and not hide baz? Is this a bug?

Versions:

$ rustc --version
rustc 1.35.0-nightly (94fd04589 2019-03-21)
$ cargo --version
cargo 1.35.0-nightly (0e35bd8af 2019-03-13)
$ rustdoc --version
rustdoc 1.35.0-nightly (94fd04589 2019-03-21)

[weiznich]

Is there any news on this?
We would like to use something like that for diesel to.

[jonhoo]

This doesn't appear to be just an issue with macros either:

/// Hello world
#[doc(hidden)]
pub struct Foo;

#[doc(inline)]
pub use Foo as Bar;

Produces entirely empty rustdoc output!

[nazar-pc]

I have a similar issue with modules:

pub mod foo {
    #[doc(hidden)]
    mod bar {
        pub struct Baz;
    }
}

#[doc(inline)]
pub use foo::bar;

Essentially I want to present nested module structure (that is used to limit visibility within crate) as non-nested in docs by leveraging re-exports.

I'm thinking of #[doc(visible)] that would override #[doc(hidden)] of the definition if applied to pub use:

pub mod foo {
    #[doc(hidden)]
    mod bar {
        pub struct Baz;
    }
}

#[doc(inline, visible)]
pub use foo::bar;

Without this when inlining is used it creates confusion since the same module is both visible at the root of the crate and nested within submodule. This also confuses IntelliJ Rust, it shows 2 suggestions for imports all the time and could use this to hide one of them.

[SergioBenitez]

This is causing quite a big issue for Rocket's docs. We'd really like to export macro_rules! macros only from specific modules, but this bug makes it impossible without also exporting them at the root.

Specifically, this:

pub mod foo {
    /// `macro_rules!`
    #[macro_export]
    macro_rules! m { () => () }

    /// `pub use m;`
    #[doc(inline)]
    pub use m;
}

Results in:

index:

modules:
foo

macros:
m `macro_rules!`

foo:

macros:
m `macro_rules!`

Which is expected. Now, by adding #[doc(hidden)] to m's declaration/definition...

    #[macro_export]
+   #[doc(hidden)]
    macro_rules! m { () => () }

...all instances of m in the docs disappear, even though foo:m is still reachable and not hidden!

[SergioBenitez]

Here's a macro that (sort of) patches around this issue:

#[macro_use]
macro_rules! export {
    (
        $(#[$m:meta])*
        macro_rules! $name:ident {
            $(($($token:tt)*) => ($($expansion:tt)*));* $(;)?
        }
    ) => (
        $(#[$m])*
        #[doc(hidden)]
        #[cfg(not(nightly))]
        #[macro_export]
        macro_rules! $name {
            $(
                ($($token)*) => ($($expansion)*)
            );*
        }

        $(#[$m])*
        #[cfg(not(nightly))]
        pub use $name;

        $(#[$m])*
        #[cfg(nightly)]
        pub macro $name {
            $(
                ($($token)*) => ($($expansion)*)
            ),*
        }
    )
}

Simply wrap a macro_rules! declaration with export!:

export! {
    macro_rules! my_macro { .. }
}

One must be careful not to use decl_macro features in expansion arms. As long as this issue exists, the macro will appear as pub use macro; in the right place without a docstring. Should this issue be fixed, nightly and stable docs will match.