Rollup merge of #92908 - dtolnay:rustdoc, r=GuillaumeGomez

Render more readable macro matcher tokens in rustdoc

Follow-up to #92334.

This PR lifts some of the token rendering logic from https://github.com/dtolnay/prettyplease into rustdoc so that even the matchers for which a source code snippet is not available (because they are macro-generated, or any other reason) follow some baseline good assumptions about where the tokens in the macro matcher are appropriate to space.

The below screenshots show an example of the difference using one of the gnarliest macros I could find. Some things to notice:

- In the **before**, notice how a couple places break in between `$(....)`↵`*`, which is just about the worst possible place that it could break.

- In the **before**, the lines that wrapped are weirdly indented by 1 space of indentation relative to column 0. In the **after**, we use the typical way of block indenting in Rust syntax which is put the open/close delimiters on their own line and indent their contents by 4 spaces relative to the previous line (so 8 spaces relative to column 0, because the matcher itself is indented by 4 relative to the `macro_rules` header).

- In the **after**, macro_rules metavariables like `$tokens:tt` are kept together, which is how just about everybody writing Rust today writes them.

## Before

![Screenshot from 2022-01-14 13-05-53](https://user-images.githubusercontent.com/1940490/149585105-1f182b78-751f-421f-a234-9dbc04fa3bbd.png)

## After

![Screenshot from 2022-01-14 13-06-04](https://user-images.githubusercontent.com/1940490/149585118-d4b52ea7-3e67-4b6e-a12b-31dfb8172f86.png)

r? `@camelid`

3 files changed, 53 insertions, 7 deletions

diff --git a/src/test/rustdoc/macro-generated-macro.macro_linebreak_pre.html b/src/test/rustdoc/macro-generated-macro.macro_linebreak_pre.html
new file mode 100644
index 00000000000..ce5d3a8461b
--- /dev/null
+++ b/src/test/rustdoc/macro-generated-macro.macro_linebreak_pre.html
@@ -0,0 +1,6 @@
+macro_rules! linebreak {
+    (
+        <= 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
+        26 27 28 =>
+    ) => { ... };
+}
\ No newline at end of file
diff --git a/src/test/rustdoc/macro-generated-macro.macro_morestuff_pre.html b/src/test/rustdoc/macro-generated-macro.macro_morestuff_pre.html
new file mode 100644
index 00000000000..28f15522a82
--- /dev/null
+++ b/src/test/rustdoc/macro-generated-macro.macro_morestuff_pre.html
@@ -0,0 +1,15 @@
+macro_rules! morestuff {
+    (
+        <= "space between most kinds of tokens" : 1 $x + @ :: >>= 'static
+        "no space inside paren or bracket" : (2 a) [2 a] $(2 $a:tt)*
+        "space inside curly brace" : { 2 a }
+        "no space inside empty delimiters" : () [] {}
+        "no space before comma or semicolon" : a, (a), { a }, a; [T; 0];
+        "the three repetition specifiers" : $(@)*, $(@)+, $(@)?
+        "repetition separators" : $(@)|*, $(@)|+, $(@)==*, $(@)static*
+        "plus or star cannot be a repetition separator" : $(@)+ * $(@)* +
+        "no space between ident and paren" : let _ = f(0) + f[0] + Struct {};
+        "space between keyword and paren" : return (a,) & for x in (..)
+        "some special case keywords" : pub(crate), fn() -> u8, Self(0, 0) =>
+    ) => { ... };
+}
\ No newline at end of file
diff --git a/src/test/rustdoc/macro-generated-macro.rs b/src/test/rustdoc/macro-generated-macro.rs
index 25d8bc3ec62..1a423cac1b5 100644
--- a/src/test/rustdoc/macro-generated-macro.rs
+++ b/src/test/rustdoc/macro-generated-macro.rs
@@ -1,14 +1,39 @@
-macro_rules! outer {
-    ($($matcher:tt)*) => {
+macro_rules! make_macro {
+    ($macro_name:ident $($matcher:tt)*) => {
         #[macro_export]
-        macro_rules! inner {
+        macro_rules! $macro_name {
             (<= $($matcher)* =>) => {};
         }
     }
 }
 
-// @has macro_generated_macro/macro.inner.html //pre 'macro_rules! inner {'
-// @has - //pre '(<= type $($i : ident) :: * + $e : expr =>) => { ... };'
-outer!(type $($i:ident)::* + $e:expr);
+// @has macro_generated_macro/macro.interpolations.html //pre 'macro_rules! interpolations {'
+// @has - //pre '(<= type $($i:ident)::* + $e:expr =>) => { ... };'
+make_macro!(interpolations type $($i:ident)::* + $e:expr);
+interpolations!(<= type foo::bar + x.sort() =>);
 
-inner!(<= type foo::bar + x.sort() =>);
+// @has macro_generated_macro/macro.attributes.html //pre 'macro_rules! attributes {'
+// @has - //pre '(<= #![no_std] #[cfg(feature = "alloc")] =>) => { ... };'
+make_macro!(attributes #![no_std] #[cfg(feature = "alloc")]);
+
+// @has macro_generated_macro/macro.groups.html //pre 'macro_rules! groups {'
+// @has - //pre '(<= fn {} () { foo[0] } =>) => { ... };'
+make_macro!(groups fn {}() {foo[0]});
+
+// @snapshot macro_linebreak_pre macro_generated_macro/macro.linebreak.html //pre/text()
+make_macro!(linebreak 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28);
+
+// @snapshot macro_morestuff_pre macro_generated_macro/macro.morestuff.html //pre/text()
+make_macro!(morestuff
+    "space between most kinds of tokens": 1 $x + @ :: >>= 'static
+    "no space inside paren or bracket": (2 a) [2 a] $(2 $a:tt)*
+    "space inside curly brace": { 2 a }
+    "no space inside empty delimiters": () [] {}
+    "no space before comma or semicolon": a, (a), { a }, a; [T; 0];
+    "the three repetition specifiers": $(@)*, $(@)+, $(@)?
+    "repetition separators": $(@)|*, $(@)|+, $(@)==*, $(@)static*
+    "plus or star cannot be a repetition separator": $(@)+ * $(@)* +
+    "no space between ident and paren": let _ = f(0) + f[0] + Struct {};
+    "space between keyword and paren": return (a,) & for x in (..)
+    "some special case keywords": pub(crate), fn() -> u8, Self(0, 0)
+);