Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc: doc(hidden) also hides re-exports #59368

Closed
ghost opened this issue Mar 22, 2019 · 11 comments · Fixed by #108241
Closed

rustdoc: doc(hidden) also hides re-exports #59368

ghost opened this issue Mar 22, 2019 · 11 comments · Fixed by #108241
Labels
C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@ghost
Copy link

ghost commented Mar 22, 2019

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:

screenshot

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)
@jonas-schievink jonas-schievink added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-macros Area: All kinds of macros (custom derive, macro_rules!, proc macros, ..) C-bug Category: This is a bug. labels Mar 22, 2019
@weiznich
Copy link
Contributor

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

@jonhoo
Copy link
Contributor

jonhoo commented Jan 23, 2020

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
Copy link

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.

@jyn514 jyn514 changed the title rustdoc: macro re-exports have no docs or are hidden rustdoc: doc(hidden) also hides re-exports Oct 11, 2020
@jyn514 jyn514 removed the A-macros Area: All kinds of macros (custom derive, macro_rules!, proc macros, ..) label Oct 11, 2020
@SergioBenitez
Copy link
Contributor

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
Copy link
Contributor

SergioBenitez commented Apr 24, 2021

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.

@SpriteOvO
Copy link
Contributor

It looks like this issue has been inactive for a while, but the problem is still there.

I would like to know if there are more comments from members about #59368 (comment)?

@danielhenrymantilla said in this reply he had a discussion with @jyn514 and @GuillaumeGomez about this, but I didn't find it. @jyn514 replied later that it looked fine to him.

@jyn514
Copy link
Member

jyn514 commented Jul 2, 2022

I'm no longer a member of the rustdoc team, please don't ping me.

bors bot added a commit to rust-embedded/embedded-hal that referenced this issue Sep 21, 2022
404: async/spi: Add a transaction helper macro r=Dirbaio a=GrantM11235

Based on #403

This macro allows users to use `SpiDevice::transaction` in a completely safe way, without needing to dereference a raw pointer.

The macro is exported as `embedded_hal_async::spi_transaction_helper` because exported macros always go in the root of the crate.
It is also publicly reexported as `embedded_hal_async::spi::transaction_helper` because I think that most people would expect to find it in the spi module.
It is not possible to apply `doc(hidden)` to the instance in the root of the crate because that would also hide the reexport, see rust-lang/rust#59368.

Co-authored-by: Grant Miller <GrantM11235@gmail.com>
JohnTitor pushed a commit to JohnTitor/rust that referenced this issue Jan 12, 2023
…, r=notriddle

Fix reexport of `doc(hidden)` item

Part of rust-lang#59368.

It doesn't fix the `doc(inline)` nor the `doc(hidden)` on macro. I'll do it in a follow-up PR.

r? `@notriddle`
@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Feb 10, 2023

Technical information for everyone following this issue: I'm working on it (well, you can infer that from my PRs I suppose). One of the last blockers is actually #[doc(hidden)]: currently we merge both the pub use's and the item's attributes. Meaning that the #[doc(hidden)] is inherited. The problem is that it's currently not possible to filter the sub-attributes of an ast::Attribute (for example, in #[doc(hidden, cfg(feature = "foo"))], we want to keep cfg(feature = "foo")).

So hopefully, once I figure out this part, I should be able to fix all the remaining issues at once.

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Feb 10, 2023
…ocs, r=notriddle

Reexported macros docs

Part of rust-lang#59368 (doesn't fix it, only improve the current situation a bit).

Macros were not correctly handled in reexports and the reexport attributes were not merged with the item either. This PR fixes both.

r? `@notriddle`
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Feb 11, 2023
…ocs, r=notriddle

Reexported macros docs

Part of rust-lang#59368 (doesn't fix it, only improve the current situation a bit).

Macros were not correctly handled in reexports and the reexport attributes were not merged with the item either. This PR fixes both.

r? `@notriddle`
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Feb 16, 2023
…erge, r=notriddle

Prevent some attributes from being merged with others on reexports

Final fix for rust-lang#59368.

As discussed on zulip [here](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/Filtering.20sub.20attributes.20in.20ast.3A.3AAttribute), we need to clone the `Attribute` to be able to filter some parts of it. Then we need to go through the attributes to able to only keep what we want (everything except a few attributes in short).

As for the second commit, when I wrote the test, I realized that the code to traverse all reexports one by one to collect all their attributes was not completely working so I fixed the few issues remaining.

r? `@notriddle`
@GuillaumeGomez
Copy link
Member

So now only one issue remains:

#[macro_export]
#[doc(hidden)]
macro_rules! foo {
    () => {};
}

pub use crate::foo as Macro; // this one isn't displayed, as expected
#[doc(inline)]
pub use crate::foo as Macro2; // this one isn't displayed but should be!

@danielhenrymantilla
Copy link
Contributor

danielhenrymantilla commented Feb 16, 2023

FWIW, "back in the day" I did have a branch with an implementation tackling your Macro2 situation, @GuillaumeGomez, if you are interested: danielhenrymantilla@c68d225

@GuillaumeGomez
Copy link
Member

I have a vague idea on how to fix it but I'm definitely interested into seeing how you did it. You sure you don't want to send a PR btw?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

9 participants