Make the documentation of builtin macro attributes accessible

[danielhenrymantilla]

use ::std::prelude::v1::derive; compiles on stable, so, AFAIK, there is no reason to have it be #[doc(hidden)].

• What it currently looks like for things such as #[test], #[derive], #[global_allocator]: https://doc.rust-lang.org/1.57.0/core/prelude/v1/index.html#:~:text=Experimental-,pub,-use%20crate%3A%3Amacros%3A%3Abuiltin%3A%3Aglobal_allocator

  

  and in ::std they're just straight hidden.

  

• Here is how it looks like with this PR (assuming the Rustc{De,En}codable ones are not reverted):

  

Since this involves doc people to chime in, and since jyn is on vacation, I'll cc @GuillaumeGomez and tag the rustdoc team as well

[danielhenrymantilla]

This is currently on a draft stage / waiting-on-author since I'd like to see if I can tackle the filtering out that happens from rustdoc as well (see the docs for ::core::prelude::v1::derive to see what I mean)

[petrochenkov]

See the FIXME above, #[doc(hidden)] was added due to rustdoc bugs causing broken links, not due to stability or instability of the attributes.

It may be possible that those bugs are fixed now, in that case the #[doc(hidden)] annotations should be just removed together with the FIXME, instead of being replaced with #[doc(no_inline)].

[petrochenkov]

Ah, wait, #[doc(no_inline)] is indeed the desired behavior for prelude imports.
Then all #[doc(hidden)]s need to be replaced with it, regardless of stability.
(You may also be able to merge some import groups after that.)

[danielhenrymantilla]

@petrochenkov So, derive seems a bit more special, since it doesn't have a public defining module to be re-exported from; thus, if using doc(no_inline), we end up with an "unclickable" item. I've thus gone with no doc override from core (so that it currently acts as inline, and would become no_inline should derive be made accessible elsewhere); but had to fall back to an explicit #[doc(inline)] override for the std reexport (I've added a comment to warn about the situation).
But I'll gladly change to whatever seems more appropriate

[petrochenkov]

since it doesn't have a public defining module to be re-exported from

This is true for all other uses of doc(hidden) in the prelude module.

[danielhenrymantilla]

So, #[global_allocator] and #[test] seem to be the only non-unstable non-deprecated attributes in the same situation, so I'm gonna apply my suggested change to those as well (whether unstable or deprecated ones deserve to be "clickable" is another question).

[chorman0773]

Anything that is stable in the standard library should be fully documented by the stdlib docs, imo. deprecated items are still stable.

…

On Fri, Dec 31, 2021 at 09:50 Daniel Henry-Mantilla < ***@***.***> wrote: So, #[global_allocator] and #[test] seem to be the only non-unstable non- deprecated attributes in the same situation, so I'm gonna apply my suggested change to those as well (whether unstable or deprecated ones deserve to be "clickable" is another question). — Reply to this email directly, view it on GitHub <#92456 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABGLD267EMO2IIARDZ5WXLDUTW7KFANCNFSM5LBHWOTQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[jyn514]

I'm on vacation.

r? @petrochenkov

[danielhenrymantilla]

@chorman0773 I've implemented 2778d53 to apply your rationale, but, that being said, the only thing one can do with Rustc{De,En}codable is pass it around, since, as a derive, they don't seem to be usable without the unstable rustc_serialize crate. So I'd lean towards making an exception for them and keep them hidden.

[chorman0773]

It's probably useful for implementors, at least for now, to know they exist. That being said, it may be reasonable to exempt them, especially if (as may be a good idea, although technically breaking) they eventually get removed/destabilzed (since they can't be used anyways).

[danielhenrymantilla]

I'll now add another commit trying to have all macros documented, regardless of stability, except for Rustc…codable

[petrochenkov]

Does this comment make sense?
The items are hidden anyway, so it doesn't make any difference whether we inline them or not?
(Especially considering that doc(inline) is the default in this situation.)

[danielhenrymantilla]

doc(inline) is the default in this situation

So, while this is currently true, I have to admit having chosen not to use doc(inline) explicitly since there is a change I've been considering to suggest to the rustdoc team, which would change, at the very least, the same-crate re-export of a #[doc(hidden)] item when not using #[doc(inline)].

For a crate wanting to feature macro_export-ed macros scoped within a module, currently, there are three options:

• pub mod module {
      #[macro_export]
      macro_rules! __m__ {() => ()}
      pub use __m__ as m;
  }

  Drawback: __m__! is visible at the crate root.

  • Workaround: use js hacks to hide it in the aftermath (an ugly example)

    Drawback: so hacky and ugly.

• Another solution: use a helper crate that performs the #[macro_export]s, and then pub use them in a scoped fashion from the frontend crate (an example).

  Drawback: on top of being more cumbersome, it breaks $crate.

The best solution for these things that occurred to me would be for #[doc(inline)] to override #[doc(hidden)] (or have a doc(inline_unhidden) for this, but that seems to be way more work). Indeed, doc(inline) expresses an intent to have the item be documented in situ, so it makes sense to have it express _unhidden semantics as well, for the rare case where it could matter.

And this would be one such case, where we'd thus have not to use doc(inline). I thus find it less error-prone to do it this way, if that makes sense?

[petrochenkov]

Ok, I don't want to dig too much into this.

[petrochenkov]

r=me after squashing commits.

[bors]

@danielhenrymantilla: 🔑 Insufficient privileges: Not in reviewers

[danielhenrymantilla]

@bors r=petrochenkov

[bors]

@danielhenrymantilla: 🔑 Insufficient privileges: Not in reviewers

[petrochenkov]

@bors r+

[bors]

📌 Commit f20ccc0 has been approved by petrochenkov