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.

Sign up for GitHub

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

Make the documentation of builtin macro attributes accessible #92456

Merged
merged 1 commit into from
Jan 4, 2022
Merged

Make the documentation of builtin macro attributes accessible #92456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions library/core/src/macros/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -866,7 +866,6 @@ pub(crate) mod builtin {
language use and is subject to change"
)]
#[allow_internal_unstable(fmt_internals)]
#[doc(hidden)]
#[rustc_builtin_macro]
#[macro_export]
macro_rules! format_args_nl {
Expand Down Expand Up @@ -1428,13 +1427,21 @@ pub(crate) mod builtin {
}

/// Attribute macro used to apply derive macros.
///
/// See [the reference] for more info.
///
/// [the reference]: ../../../reference/attributes/derive.html
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_builtin_macro]
pub macro derive($item:item) {
/* compiler built-in */
}

/// Attribute macro applied to a function to turn it into a unit test.
///
/// See [the reference] for more info.
///
/// [the reference]: ../../../reference/attributes/testing.html#the-test-attribute
#[stable(feature = "rust1", since = "1.0.0")]
#[allow_internal_unstable(test, rustc_attrs)]
#[rustc_builtin_macro]
Expand Down Expand Up @@ -1469,7 +1476,7 @@ pub(crate) mod builtin {

/// Attribute macro applied to a static to register it as a global allocator.
///
/// See also [`std::alloc::GlobalAlloc`](../std/alloc/trait.GlobalAlloc.html).
/// See also [`std::alloc::GlobalAlloc`](../../../std/alloc/trait.GlobalAlloc.html).
#[stable(feature = "global_allocator", since = "1.28.0")]
#[allow_internal_unstable(rustc_attrs)]
#[rustc_builtin_macro]
Expand Down Expand Up @@ -1507,6 +1514,7 @@ pub(crate) mod builtin {
since = "1.52.0",
reason = "rustc-serialize is deprecated and no longer supported"
)]
#[doc(hidden)] // While technically stable, using it is unstable, and deprecated. Hide it.
pub macro RustcDecodable($item:item) {
/* compiler built-in */
}
Expand All @@ -1519,6 +1527,7 @@ pub(crate) mod builtin {
since = "1.52.0",
reason = "rustc-serialize is deprecated and no longer supported"
)]
#[doc(hidden)] // While technically stable, using it is unstable, and deprecated. Hide it.
pub macro RustcEncodable($item:item) {
/* compiler built-in */
}
Expand Down
15 changes: 6 additions & 9 deletions library/core/src/prelude/v1.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,29 +69,26 @@ pub use crate::{
#[doc(no_inline)]
pub use crate::concat_bytes;

// Do not `doc(inline)` these `doc(hidden)` items.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow(deprecated, deprecated_in_future)]
#[doc(no_inline)]
pub use crate::macros::builtin::{
bench, global_allocator, test, test_case, RustcDecodable, RustcEncodable,
};
#[allow(deprecated)]
pub use crate::macros::builtin::{RustcDecodable, RustcEncodable};

// Do not `doc(no_inline)` so that they become doc items on their own
// (no public module for them to be re-exported from).
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[doc(no_inline)]
pub use crate::macros::builtin::derive;
pub use crate::macros::builtin::{bench, derive, global_allocator, test, test_case};

#[unstable(
feature = "cfg_accessible",
issue = "64797",
reason = "`cfg_accessible` is not fully implemented"
)]
#[doc(no_inline)]
pub use crate::macros::builtin::cfg_accessible;

#[unstable(
feature = "cfg_eval",
issue = "82679",
reason = "`cfg_eval` is a recently implemented feature"
)]
#[doc(no_inline)]
pub use crate::macros::builtin::cfg_eval;
19 changes: 8 additions & 11 deletions library/std/src/prelude/v1.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,33 +54,30 @@ pub use core::prelude::v1::{
#[doc(no_inline)]
pub use core::prelude::v1::concat_bytes;

// FIXME: Attribute and internal derive macros are not documented because for them rustdoc generates
// dead links which fail link checker testing.
// Do not `doc(inline)` these `doc(hidden)` items.
petrochenkov marked this conversation as resolved.
Show resolved Hide resolved
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow(deprecated, deprecated_in_future)]
#[doc(hidden)]
pub use core::prelude::v1::{
bench, global_allocator, test, test_case, RustcDecodable, RustcEncodable,
};
#[allow(deprecated)]
pub use core::prelude::v1::{RustcDecodable, RustcEncodable};

// Do not `doc(no_inline)` so that they become doc items on their own
// (no public module for them to be re-exported from).
petrochenkov marked this conversation as resolved.
Show resolved Hide resolved
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[doc(hidden)]
pub use core::prelude::v1::derive;
pub use core::prelude::v1::{bench, derive, global_allocator, test, test_case};

// Do not `doc(no_inline)` either.
#[unstable(
feature = "cfg_accessible",
issue = "64797",
reason = "`cfg_accessible` is not fully implemented"
)]
#[doc(hidden)]
pub use core::prelude::v1::cfg_accessible;

// Do not `doc(no_inline)` either.
#[unstable(
feature = "cfg_eval",
issue = "82679",
reason = "`cfg_eval` is a recently implemented feature"
)]
#[doc(hidden)]
pub use core::prelude::v1::cfg_eval;

// The file so far is equivalent to src/libcore/prelude/v1.rs,
Expand Down