From f20ccc07489bff158b41a6bafd822366ac249cab Mon Sep 17 00:00:00 2001 From: Daniel Henry-Mantilla Date: Fri, 31 Dec 2021 13:32:03 +0100 Subject: [PATCH] Make the documentation of builtin macro attributes accessible - Do not `#[doc(hidden)]` the `#[derive]` macro attribute - Add a link to the reference section to `derive`'s inherent docs - Do the same for `#[test]` and `#[global_allocator]` - Fix `GlobalAlloc` link (why is it on `core` and not `alloc`?) - Try `no_inline`-ing the `std` reexports from `core` - Revert "Try `no_inline`-ing the `std` reexports from `core`" - Address PR review - Also document the unstable macros --- library/core/src/macros/mod.rs | 13 +++++++++++-- library/core/src/prelude/v1.rs | 15 ++++++--------- library/std/src/prelude/v1.rs | 19 ++++++++----------- 3 files changed, 25 insertions(+), 22 deletions(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index d9389892c0cd6..d8f6c85e428cd 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -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 { @@ -1428,6 +1427,10 @@ 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) { @@ -1435,6 +1438,10 @@ pub(crate) mod builtin { } /// 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] @@ -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] @@ -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 */ } @@ -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 */ } diff --git a/library/core/src/prelude/v1.rs b/library/core/src/prelude/v1.rs index 54f498d1dc15e..0fb8846288bee 100644 --- a/library/core/src/prelude/v1.rs +++ b/library/core/src/prelude/v1.rs @@ -69,23 +69,21 @@ pub use crate::{ #[doc(no_inline)] pub use crate::concat_bytes; +// Do not `doc(inline)` these `doc(hidden)` items. #[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( @@ -93,5 +91,4 @@ pub use crate::macros::builtin::cfg_accessible; issue = "82679", reason = "`cfg_eval` is a recently implemented feature" )] -#[doc(no_inline)] pub use crate::macros::builtin::cfg_eval; diff --git a/library/std/src/prelude/v1.rs b/library/std/src/prelude/v1.rs index 743dd51333d18..b52bcdfca9e07 100644 --- a/library/std/src/prelude/v1.rs +++ b/library/std/src/prelude/v1.rs @@ -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. #[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). #[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,