apply unstable book suggestions

- Clarifies the uses of implicit and explicit deref patterns
- Adapts the example to provide a use for explicit `deref!(_)`
- Replaces binding mode annotations with refs on the scrutinee
- Cross-links with `string_deref_patterns` and clarifies their relation

The example is still contrived, but hopefully the intent comes across.

Author: dianne

src/doc/unstable-book/src/language-features/deref-patterns.md

@@ -6,21 +6,31 @@ The tracking issue for this feature is: [#87121]
 
 ------------------------
 
-This feature permits pattern matching on [library-defined smart pointers] through their `Deref`
-target types, either implicitly or with the placeholder `deref!(_)` syntax.
+This feature permits pattern matching on [smart pointers in the standard library] through their
+`Deref` target types, either implicitly or with explicit `deref!(_)` patterns (the syntax of which
+is currently a placeholder).
 
 ```rust
 #![feature(deref_patterns)]
 #![allow(incomplete_features)]
 
 pub fn main() {
     let mut v = vec![Box::new(Some(0))];
-    if let [Some(ref mut x)] = v {
+
+    // Implicit dereferences are inserted when a pattern can match against the
+    // result of repeatedly dereferencing but can't match against a smart
+    // pointer itself. This works alongside match ergonomics for references.
+    if let [Some(x)] = &mut v {
         *x += 1;
     }
-    if let deref!([deref!(Some(ref mut x))]) = v {
-        *x += 1;
+
+    // Explicit `deref!(_)` patterns may instead be used when finer control is
+    // needed, e.g. to dereference only a single smart pointer, or to bind the
+    // the result of dereferencing to a variable.
+    if let deref!([deref!(opt_x @ Some(1))]) = &mut v {
+        opt_x.as_mut().map(|x| *x += 1);
     }
+
     assert_eq!(v, [Box::new(Some(2))]);
 }
 ```
@@ -31,18 +41,22 @@ when matching on nested structures:
 ```rust
 pub fn main() {
     let mut v = vec![Box::new(Some(0))];
-    if let [ref mut b] = *v {
-        if let Some(ref mut x) = **b {
+    if let [b] = &mut *v {
+        if let Some(x) = &mut **b {
             *x += 1;
         }
     }
-    if let [ref mut b] = *v {
-        if let Some(ref mut x) = **b {
-            *x += 1;
+    if let [b] = &mut *v {
+        if let opt_x @ Some(1) = &mut **b {
+            opt_x.as_mut().map(|x| *x += 1);
         }
     }
     assert_eq!(v, [Box::new(Some(2))]);
 }
 ```
 
-[library-defined smart pointers]: https://doc.rust-lang.org/std/ops/trait.DerefPure.html#implementors
+This does not yet implement the functionality of [`string_deref_patterns`], but it is intended to
+supersede that feature once it supports matching with string literals.
+
+[smart pointers in the standard library]: https://doc.rust-lang.org/std/ops/trait.DerefPure.html#implementors
+[`string_deref_patterns`]: ./string-deref-patterns.md

src/doc/unstable-book/src/language-features/string-deref-patterns.md

@@ -42,4 +42,9 @@ pub fn is_it_the_answer(value: Value) -> bool {
 }
 ```
 
+See also the [`deref_patterns`] feature, a generalization of `string_deref_patterns` to other smart
+pointers. Once [`deref_patterns`] supports matching with string literals, it is intended to
+supersede `string_deref_patterns`.
+
 [its `Deref` implementation]: https://doc.rust-lang.org/std/string/struct.String.html#impl-Deref-for-String
+[`deref_patterns`]: ./deref-patterns.md