Rewrite try to be written in terms of the Try trait

This rewrites the section to say that it uses the `Try` trait. I felt it
was a bit too awkward to avoid it (since it is unstable).

This keeps an explicit list of the types that the `Try` trait is
implemented for, and adds the missing types (like `ControlFlow`).

The intent is that when `Try` is stabilized that the desuggaring note
moves to a normative rule, the `expr.try.restricted-types` rule is
removed (and instead direct the user to the standard library
documentation).

I'm still holding out hope that they change the terminology, since I
think the current choice is going to be confusing.

This has a hack to allow `feature(try_trait_v2)` by abusing the style
checker by adding some spaces. I really wanted to keep this example
tested to ensure that it is kept up-to-date. However, I may regret this
in the future.

Fixes #1927

Author: ehuss

src/expressions/operator-expr.md

@@ -198,7 +198,7 @@ TryPropagationExpression -> Expression `?`
 ```
 
 r[expr.try.intro]
-The try propagation operator (`?`) unwraps valid values or returns erroneous values, propagating them to the calling function.
+The try propagation expression uses the [`core::ops::Try`] trait to evaluate the subexpression to either a value, or to return a value.
 
 > [!EXAMPLE]
 > The following examples illustrate some basic uses of the try propagation expression.
@@ -269,32 +269,48 @@ The try propagation operator (`?`) unwraps valid values or returns erroneous val
 > # }
 > ```
 
+> [!NOTE]
+> The [`core::ops::Try`] trait is currently unstable, and thus cannot be implemented for user types without using the nightly release channel.
+>
+> The try propagation expression is currently equivalent to:
+>
+> ```rust
+> # #![ feature(try_trait_v2) ]
+> # fn example() -> Result<(), ()> {
+> # let expr = Ok(());
+> match core::ops::Try::branch(expr) {
+>     core::ops::ControlFlow::Continue(val) => val,
+>     core::ops::ControlFlow::Break(residual) =>
+>         return core::ops::FromResidual::from_residual(residual),
+> }
+> # Ok(())
+> # }
+> ```
+
 > [!NOTE]
 > The try propagation operator is sometimes called *the question mark operator*, *the `?` operator*, or *the try operator*.
 
 r[expr.try.restricted-types]
-It is a unary postfix operator that can only be applied to the types `Result<T, E>` and `Option<T>`.
-
-r[expr.try.behavior-std-result]
-When applied to values of the `Result<T, E>` type, it propagates errors.
-
-r[expr.try.effects-err]
-If the value is `Err(e)`, then it will return `Err(From::from(e))` from the enclosing function or closure.
-
-r[expr.try.result-ok]
-If applied to `Ok(x)`, then it will unwrap the value to evaluate to `x`.
-
-r[expr.try.behavior-std-option]
-When applied to values of the `Option<T>` type, it propagates `None`s.
-
-r[expr.try.effects-none]
-If the value is `None`, then it will return `None`.
-
-r[expr.try.result-some]
-If applied to `Some(x)`, then it will unwrap the value to evaluate to `x`.
-
-r[expr.try.trait]
-`?` cannot be overloaded.
+The try propagation operator can be applied to expressions with the type of:
+
+- [`Result<T, E>`]
+    - `Result::Ok(val)` evaluates to the value of `val`
+    - `Result::Err(e)` returns the value of `Result::Err(From::from(e))`
+- [`Option<T>`]
+    - `Option::Some(val)` evaluates to the value of `val`
+    - `Option::None` returns the value `Option::None`
+- [`ControlFlow<B, C>`][core::ops::ControlFlow]
+    - `ControlFlow::Continue(c)` evaluates to value of `c`
+    - `ControlFlow::Break(b)` returns the value `ControlFlow::Break(b)`
+- [`Poll<Result<T, E>>`][core::task::Poll]
+    - `Poll::Ready(Ok(val))` evaluates to the value `Poll::Ready(val)`
+    - `Poll::Ready(Err(e))` returns the value `Poll::Ready(Err(From::from(e)))`
+    - `Poll::Pending` evaluates to the value `Poll::Pending`
+- [`Poll<Option<Result<T, E>>>`][`core::task::Poll`]
+    - `Poll::Ready(Some(Ok(val)))` evaluates to the value `Poll::Ready(Some(val))`
+    - `Poll::Ready(Some(Err(e)))` returns the value `Poll::Ready(Some(Err(From::from(e))))`
+    - `Poll::Ready(None)` evaluates to the value `Poll::Ready(None)`
+    - `Poll::Pending` evaluates to the value `Poll::Pending`
 
 r[expr.negate]
 ## Negation operators