Rollup merge of #62243 - petrochenkov:macrodoc, r=eddyb

Improve documentation for built-in macros

This is the `libcore` part of https://github.com/rust-lang/rust/pull/62086.
Right now the only effect is improved documentation.

The changes in the last few commits are required to make the `libcore` change compile successfully.

8 files changed, 74 insertions, 22 deletions

diff --git a/src/test/ui/hygiene/auxiliary/transparent-basic.rs b/src/test/ui/hygiene/auxiliary/transparent-basic.rs
index 0d045d09d2c..37de27ee800 100644
--- a/src/test/ui/hygiene/auxiliary/transparent-basic.rs
+++ b/src/test/ui/hygiene/auxiliary/transparent-basic.rs
@@ -1,6 +1,6 @@
 #![feature(decl_macro, rustc_attrs)]
 
-#[rustc_transparent_macro]
+#[rustc_macro_transparency = "transparent"]
 pub macro dollar_crate() {
     let s = $crate::S;
 }
diff --git a/src/test/ui/hygiene/generate-mod.rs b/src/test/ui/hygiene/generate-mod.rs
index 089d74f123e..8826293542c 100644
--- a/src/test/ui/hygiene/generate-mod.rs
+++ b/src/test/ui/hygiene/generate-mod.rs
@@ -11,7 +11,7 @@ macro genmod($FromOutside: ident, $Outer: ident) {
     }
 }
 
-#[rustc_transparent_macro]
+#[rustc_macro_transparency = "transparent"]
 macro genmod_transparent() {
     type A = FromOutside;
     struct Outer;
diff --git a/src/test/ui/hygiene/rustc-macro-transparency.rs b/src/test/ui/hygiene/rustc-macro-transparency.rs
new file mode 100644
index 00000000000..a0a3d411d28
--- /dev/null
+++ b/src/test/ui/hygiene/rustc-macro-transparency.rs
@@ -0,0 +1,31 @@
+#![feature(decl_macro, rustc_attrs)]
+
+#[rustc_macro_transparency = "transparent"]
+macro transparent() {
+    struct Transparent;
+    let transparent = 0;
+}
+#[rustc_macro_transparency = "semitransparent"]
+macro semitransparent() {
+    struct SemiTransparent;
+    let semitransparent = 0;
+}
+#[rustc_macro_transparency = "opaque"]
+macro opaque() {
+    struct Opaque;
+    let opaque = 0;
+}
+
+fn main() {
+    transparent!();
+    semitransparent!();
+    opaque!();
+
+    Transparent; // OK
+    SemiTransparent; // OK
+    Opaque; //~ ERROR cannot find value `Opaque` in this scope
+
+    transparent; // OK
+    semitransparent; //~ ERROR cannot find value `semitransparent` in this scope
+    opaque; //~ ERROR cannot find value `opaque` in this scope
+}
diff --git a/src/test/ui/hygiene/rustc-macro-transparency.stderr b/src/test/ui/hygiene/rustc-macro-transparency.stderr
new file mode 100644
index 00000000000..2a9df221e2c
--- /dev/null
+++ b/src/test/ui/hygiene/rustc-macro-transparency.stderr
@@ -0,0 +1,21 @@
+error[E0425]: cannot find value `Opaque` in this scope
+  --> $DIR/rustc-macro-transparency.rs:26:5
+   |
+LL |     Opaque;
+   |     ^^^^^^ help: a local variable with a similar name exists: `opaque`
+
+error[E0425]: cannot find value `semitransparent` in this scope
+  --> $DIR/rustc-macro-transparency.rs:29:5
+   |
+LL |     semitransparent;
+   |     ^^^^^^^^^^^^^^^ not found in this scope
+
+error[E0425]: cannot find value `opaque` in this scope
+  --> $DIR/rustc-macro-transparency.rs:30:5
+   |
+LL |     opaque;
+   |     ^^^^^^ not found in this scope
+
+error: aborting due to 3 previous errors
+
+For more information about this error, try `rustc --explain E0425`.
diff --git a/src/test/ui/hygiene/transparent-basic.rs b/src/test/ui/hygiene/transparent-basic.rs
index 23ee558cc17..69dfc524989 100644
--- a/src/test/ui/hygiene/transparent-basic.rs
+++ b/src/test/ui/hygiene/transparent-basic.rs
@@ -5,12 +5,12 @@
 
 extern crate transparent_basic;
 
-#[rustc_transparent_macro]
+#[rustc_macro_transparency = "transparent"]
 macro binding() {
     let x = 10;
 }
 
-#[rustc_transparent_macro]
+#[rustc_macro_transparency = "transparent"]
 macro label() {
     break 'label
 }
diff --git a/src/test/ui/macros/restricted-shadowing-modern.rs b/src/test/ui/macros/restricted-shadowing-modern.rs
index 448f623c220..a8818507d75 100644
--- a/src/test/ui/macros/restricted-shadowing-modern.rs
+++ b/src/test/ui/macros/restricted-shadowing-modern.rs
@@ -80,17 +80,17 @@
 struct Right;
 // struct Wrong; // not defined
 
-#[rustc_transparent_macro]
+#[rustc_macro_transparency = "transparent"]
 macro include() {
-    #[rustc_transparent_macro]
+    #[rustc_macro_transparency = "transparent"]
     macro gen_outer() {
         macro m() { Wrong }
     }
-    #[rustc_transparent_macro]
+    #[rustc_macro_transparency = "transparent"]
     macro gen_inner() {
         macro m() { Right }
     }
-    #[rustc_transparent_macro]
+    #[rustc_macro_transparency = "transparent"]
     macro gen_invoc() {
         m!()
     }
@@ -100,7 +100,7 @@ macro include() {
     fn check1() {
         macro m() {}
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_gen_inner_invoc() {
                 gen_inner!();
                 m!(); //~ ERROR `m` is ambiguous
@@ -112,7 +112,7 @@ macro include() {
     fn check5() {
         macro m() { Wrong }
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_inner_invoc() {
                 macro m() { Right }
                 m!(); // OK
@@ -124,7 +124,7 @@ macro include() {
     fn check9() {
         macro m() { Wrong }
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_inner_gen_invoc() {
                 macro m() { Right }
                 gen_invoc!(); // OK
@@ -145,7 +145,7 @@ macro include() {
         macro m() {}
         {
             gen_inner!();
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_invoc() { m!() } //~ ERROR `m` is ambiguous
             gen_invoc!();
         }
@@ -186,7 +186,7 @@ macro include() {
     fn check52() {
         gen_outer!();
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_gen_inner_invoc() {
                 gen_inner!();
                 m!(); //~ ERROR `m` is ambiguous
@@ -198,7 +198,7 @@ macro include() {
     fn check56() {
         gen_outer!();
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_inner_invoc() {
                 macro m() { Right }
                 m!(); // OK
@@ -218,7 +218,7 @@ macro include() {
     fn check60() {
         gen_outer!();
         {
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_inner_gen_invoc() {
                 macro m() { Right }
                 gen_invoc!(); // OK
@@ -231,7 +231,7 @@ macro include() {
         gen_outer!();
         {
             gen_inner!();
-            #[rustc_transparent_macro]
+            #[rustc_macro_transparency = "transparent"]
             macro gen_invoc() { m!() } //~ ERROR `m` is ambiguous
             gen_invoc!();
         }
diff --git a/src/test/ui/proc-macro/reserved-macro-names.rs b/src/test/ui/proc-macro/reserved-macro-names.rs
index 7c66af172fd..9f56eccb7a6 100644
--- a/src/test/ui/proc-macro/reserved-macro-names.rs
+++ b/src/test/ui/proc-macro/reserved-macro-names.rs
@@ -8,18 +8,18 @@ use proc_macro::*;
 
 #[proc_macro_attribute]
 pub fn cfg(_: TokenStream, input: TokenStream) -> TokenStream {
-    //~^ ERROR name `cfg` is reserved in macro namespace
+    //~^ ERROR name `cfg` is reserved in attribute namespace
     input
 }
 
 #[proc_macro_attribute]
 pub fn cfg_attr(_: TokenStream, input: TokenStream) -> TokenStream {
-    //~^ ERROR name `cfg_attr` is reserved in macro namespace
+    //~^ ERROR name `cfg_attr` is reserved in attribute namespace
     input
 }
 
 #[proc_macro_attribute]
 pub fn derive(_: TokenStream, input: TokenStream) -> TokenStream {
-    //~^ ERROR name `derive` is reserved in macro namespace
+    //~^ ERROR name `derive` is reserved in attribute namespace
     input
 }
diff --git a/src/test/ui/proc-macro/reserved-macro-names.stderr b/src/test/ui/proc-macro/reserved-macro-names.stderr
index 5ebe62a4969..f871e43ce51 100644
--- a/src/test/ui/proc-macro/reserved-macro-names.stderr
+++ b/src/test/ui/proc-macro/reserved-macro-names.stderr
@@ -1,16 +1,16 @@
-error: name `cfg` is reserved in macro namespace
+error: name `cfg` is reserved in attribute namespace
   --> $DIR/reserved-macro-names.rs:10:8
    |
 LL | pub fn cfg(_: TokenStream, input: TokenStream) -> TokenStream {
    |        ^^^
 
-error: name `cfg_attr` is reserved in macro namespace
+error: name `cfg_attr` is reserved in attribute namespace
   --> $DIR/reserved-macro-names.rs:16:8
    |
 LL | pub fn cfg_attr(_: TokenStream, input: TokenStream) -> TokenStream {
    |        ^^^^^^^^
 
-error: name `derive` is reserved in macro namespace
+error: name `derive` is reserved in attribute namespace
   --> $DIR/reserved-macro-names.rs:22:8
    |
 LL | pub fn derive(_: TokenStream, input: TokenStream) -> TokenStream {