Rollup merge of #92456 - danielhenrymantilla:patch-1, r=petrochenkov

Make the documentation of builtin macro attributes accessible

`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

    <img width="767" alt="Screen Shot 2021-12-31 at 17 49 46" src="https://user-images.githubusercontent.com/9920355/147832999-cbd747a6-4607-4df6-8e57-c1675dcbc1c3.png">

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

    <img width="452" alt="Screen Shot 2021-12-31 at 17 53 18" src="https://user-images.githubusercontent.com/9920355/147833105-c5ff8cd1-9e4d-4d2b-9621-b36aa3cfcb28.png">

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

    <img width="778" alt="Screen Shot 2021-12-31 at 17 50 55" src="https://user-images.githubusercontent.com/9920355/147833034-84286342-dbf7-4e6e-9062-f39cd6c286a4.png">

    <img width="291" alt="Screen Shot 2021-12-31 at 17 52 54" src="https://user-images.githubusercontent.com/9920355/147833109-c92ed55c-51c6-40a2-9205-f834d1e349c0.png">

 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

3 files changed, 25 insertions, 22 deletions

diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs
index d9389892c0c..d8f6c85e428 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 54f498d1dc1..0fb8846288b 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 743dd51333d..b52bcdfca9e 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,