Rollup merge of #137358 - dianne:new-match-ergonomics-examples, r=Nadrieril

Match Ergonomics 2024: add context and examples to the unstable book

The examples here are pretty limited and don't illustrate the differences between the two feature gates, but my hope is that they get the general idea across. I can try and add some more nuance or more comprehensive examples too if that would help.

Hopefully the doctest isn't too sneaky. I wanted to make the bindings' types explicit, and the most readable way I could think of was to use a helper.

~~Unfortunately it looks like the "run this code" button doesn't work yet, but I made sure the examples are cross-edition, so that should resolve on its own once playground's nightly updates (or if playground's default becomes edition 2024, or if the edition in the markdown gets forwarded to playground).~~ It looks like the default edition on playground is now 2024, so the run button works! There's no output, but having a button to show that it compiles is nice, I think.

Relevant tracking issue: #123076

r? ``````@Nadrieril``````

2 files changed, 47 insertions, 6 deletions

diff --git a/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024-structural.md b/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024-structural.md
index bfdb579cd35..b2f59732801 100644
--- a/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024-structural.md
+++ b/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024-structural.md
@@ -9,12 +9,32 @@ The tracking issue for this feature is: [#123076]
 This feature is incomplete and not yet intended for general use.
 
 This implements experimental, Edition-dependent match ergonomics under consideration for inclusion
-in Rust.
-For more information, see the corresponding typing rules for [Editions 2021 and earlier] and for
-[Editions 2024 and later].
+in Rust, allowing `&` patterns in more places. For example:
+```rust,edition2024
+#![feature(ref_pat_eat_one_layer_2024_structural)]
+#![allow(incomplete_features)]
+#
+# // Tests type equality in a way that avoids coercing `&&T` or `&mut T` to `&T`.
+# trait Eq<T> {}
+# impl<T> Eq<T> for T {}
+# fn has_type<T>(_: impl Eq<T>) {}
+
+// `&` can match against a `ref` binding mode instead of a reference type:
+let (x, &y) = &(0, 1);
+has_type::<&u8>(x);
+has_type::<u8>(y);
+
+// `&` can match against `&mut` references:
+let &z = &mut 2;
+has_type::<u8>(z);
+```
+
+For specifics, see the corresponding typing rules for [Editions 2021 and earlier] and for
+[Editions 2024 and later]. For more information on binding modes, see [The Rust Reference].
 
 For alternative experimental match ergonomics, see the feature
 [`ref_pat_eat_one_layer_2024`](./ref-pat-eat-one-layer-2024.md).
 
 [Editions 2021 and earlier]: https://nadrieril.github.io/typing-rust-patterns/?compare=false&opts1=AQEBAQIBAQEBAAAAAAAAAAAAAAAAAAA%3D&mode=rules&do_cmp=false
 [Editions 2024 and later]: https://nadrieril.github.io/typing-rust-patterns/?compare=false&opts1=AQEBAgEBAQEBAgIAAAAAAAAAAAAAAAA%3D&mode=rules&do_cmp=false
+[The Rust Reference]: https://doc.rust-lang.org/reference/patterns.html#binding-modes
diff --git a/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024.md b/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024.md
index 0c90cec0dbd..f7c85eec2d2 100644
--- a/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024.md
+++ b/src/doc/unstable-book/src/language-features/ref-pat-eat-one-layer-2024.md
@@ -9,12 +9,33 @@ The tracking issue for this feature is: [#123076]
 This feature is incomplete and not yet intended for general use.
 
 This implements experimental, Edition-dependent match ergonomics under consideration for inclusion
-in Rust.
-For more information, see the corresponding typing rules for [Editions 2021 and earlier] and for
-[Editions 2024 and later].
+in Rust, allowing `&` patterns in more places. For example:
+
+```rust,edition2024
+#![feature(ref_pat_eat_one_layer_2024)]
+#![allow(incomplete_features)]
+#
+# // Tests type equality in a way that avoids coercing `&&T` or `&mut T` to `&T`.
+# trait Eq<T> {}
+# impl<T> Eq<T> for T {}
+# fn has_type<T>(_: impl Eq<T>) {}
+
+// `&` can match against a `ref` binding mode instead of a reference type:
+let (x, &y) = &(0, 1);
+has_type::<&u8>(x);
+has_type::<u8>(y);
+
+// `&` can match against `&mut` references:
+let &z = &mut 2;
+has_type::<u8>(z);
+```
+
+For specifics, see the corresponding typing rules for [Editions 2021 and earlier] and for
+[Editions 2024 and later]. For more information on binding modes, see [The Rust Reference].
 
 For alternative experimental match ergonomics, see the feature
 [`ref_pat_eat_one_layer_2024_structural`](./ref-pat-eat-one-layer-2024-structural.md).
 
 [Editions 2021 and earlier]: https://nadrieril.github.io/typing-rust-patterns/?compare=false&opts1=AQEBAQIBAQABAAAAAQEBAAEBAAABAAA%3D&mode=rules&do_cmp=false
 [Editions 2024 and later]: https://nadrieril.github.io/typing-rust-patterns/?compare=false&opts1=AQEBAAABAQABAgIAAQEBAAEBAAABAAA%3D&mode=rules&do_cmp=false
+[The Rust Reference]: https://doc.rust-lang.org/reference/patterns.html#binding-modes