-
Notifications
You must be signed in to change notification settings - Fork 12.7k
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
Comments
Is there any news on this? |
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! |
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 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. |
This is causing quite a big issue for Rocket's docs. We'd really like to export Specifically, this: pub mod foo {
/// `macro_rules!`
#[macro_export]
macro_rules! m { () => () }
/// `pub use m;`
#[doc(inline)]
pub use m;
} Results in: index:
foo:
Which is expected. Now, by adding #[macro_export]
+ #[doc(hidden)]
macro_rules! m { () => () } ...all instances of |
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 export! {
macro_rules! my_macro { .. }
} One must be careful not to use |
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. |
I'm no longer a member of the rustdoc team, please don't ping me. |
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>
…, 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`
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 So hopefully, once I figure out this part, I should be able to fix all the remaining issues at once. |
…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`
…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`
…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`
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! |
FWIW, "back in the day" I did have a branch with an implementation tackling your |
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? |
Code:
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 hidefoo
and not hidebaz
? Is this a bug?Versions:
The text was updated successfully, but these errors were encountered: