Update for stabilization of the never type

src/attributes/diagnostics.md

@@ -401,11 +401,10 @@ As an exception to [attributes.diagnostics.must_use.type], the lint does not fir
 ```rust
 #![deny(unused_must_use)]
 # use core::ops::ControlFlow;
-enum Empty {}
-fn f1() -> Result<(), Empty> { Ok(()) }
-f1(); // OK: `Empty` is uninhabited.
-fn f2() -> ControlFlow<Empty, ()> { ControlFlow::Continue(()) }
-f2(); // OK: `Empty` is uninhabited.
+fn f1() -> Result<(), !> { Ok(()) }
+f1(); // OK: `!` is uninhabited.
+fn f2() -> ControlFlow<!, ()> { ControlFlow::Continue(()) }
+f2(); // OK: `!` is uninhabited.
 ```
 
 r[attributes.diagnostics.must_use.fn]

src/divergence.md

@@ -27,7 +27,6 @@ See the following rules for specific expression divergence behavior:
 - [expr.match.diverging] --- `match` expressions.
 - [expr.match.empty] --- Empty `match` expressions.
 - [expr.return.diverging] --- `return` expressions.
-- [type.never.constraint] --- Function calls returning `!`.
 
 > [!NOTE]
 > The [`panic!`] macro and related panic-generating macros like [`unreachable!`] also have the type [`!`] and are diverging.
@@ -75,9 +74,6 @@ If a type to be inferred is only unified with diverging expressions, then that t
 > };
 > ```
 
-> [!EDITION-2024]
-> Before the 2024 edition, the type was inferred to instead be `()`.
-
 > [!NOTE]
 > Importantly, type unification may happen *structurally*, so the fallback `!` may be part of a larger type. The following compiles:
 >

src/expressions/block-expr.md

@@ -91,7 +91,6 @@ r[expr.block.diverging]
 A block is considered to be [diverging][divergence] if all reachable control flow paths contain a diverging expression, unless that expression is a [place expression] that is not read from.
 
 ```rust,no_run
-# #![ feature(never_type) ]
 fn no_control_flow() -> ! {
     // There are no conditional statements, so this entire function body is diverging.
     loop {}
@@ -115,10 +114,6 @@ fn control_flow_not_diverging() -> () {
     }
 }
 
-// Note: This makes use of the unstable never type which is only available on
-// Rust's nightly channel. This is done for illustration purposes. It is
-// possible to encounter this scenario in stable Rust, but requires a more
-// convoluted example.
 struct Foo {
     x: !,
 }
@@ -133,7 +128,6 @@ fn diverging_place_read() -> ! {
 ```
 
 ```rust,compile_fail,E0308
-# #![ feature(never_type) ]
 # fn make<T>() -> T { loop {} }
 # struct Foo {
 #     x: !,

src/expressions/match-expr.md

@@ -119,11 +119,9 @@ If there are no match arms, then the `match` expression is [diverging] and the t
 
 > [!EXAMPLE]
 > ```rust
-> # fn make<T>() -> T { loop {} }
 > enum Empty {}
 >
-> fn diverging_match_no_arms() -> ! {
->     let e: Empty = make();
+> fn diverging_match_no_arms(e: Empty) -> ! {
 >     match e {}
 > }
 > ```

src/types/closure.md

@@ -340,8 +340,7 @@ r[type.closure.capture.precision.discriminants.uninhabited-variants]
 Even if all variants but the one being matched against are uninhabited, making the pattern [irrefutable][patterns.refutable], the discriminant is still read if it otherwise would be.
 
 ```rust,compile_fail,E0502
-enum Empty {}
-let mut x = Ok::<_, Empty>(42);
+let mut x = Ok::<_, !>(42);
 let c = || {
     let Ok(_) = x; // Captures `x` by `ImmBorrow`.
 };

src/types/never.md

@@ -1,28 +1,42 @@
 r[type.never]
 # Never type
 
-r[type.never.syntax]
-```grammar,types
-NeverType -> `!`
-```
-
 r[type.never.intro]
-The never type `!` is a type with no values, representing the result of computations that never complete.
+The never type `!` is a type with no values, representing computations that never complete, also known as [diverging][divergence] computations.
 
-r[type.never.coercion]
-Expressions of type `!` can be coerced into any other type.
+> [!EXAMPLE]
+> ```rust
+> fn foo() -> ! {
+>     panic!("This call never returns.");
+> }
+> ```
+>
+> ```rust
+> unsafe extern "C" {
+>     pub safe fn no_return_extern_func() -> !;
+> }
+> ```
+>
+> ```rust
+> # use std::str::FromStr;
+> struct Anything(String);
+>
+> impl FromStr for Anything {
+>     type Err = !;
+>
+>     fn from_str(s: &str) -> Result<Self, !> {
+>         Ok(Anything(s.to_owned()))
+>     }
+> }
+>
+> let Ok(s) = Anything::from_str("example");
+> ```
 
-r[type.never.constraint]
-The `!` type can **only** appear in function return types presently, indicating it is a diverging function that never returns.
 
-```rust
-fn foo() -> ! {
-    panic!("This call never returns.");
-}
+r[type.never.syntax]
+```grammar,types
+NeverType -> `!`
 ```
 
-```rust
-unsafe extern "C" {
-    pub safe fn no_return_extern_func() -> !;
-}
-```
+r[type.never.coercion]
+Expressions of type `!` can be coerced into any type.