Merge pull request #62235 from bradleymackey/feature/never-doc

stdlib: Improve Never documentation

Author: amartini51

stdlib/public/core/Policy.swift

@@ -15,16 +15,49 @@
 //===----------------------------------------------------------------------===//
 // Standardized uninhabited type
 //===----------------------------------------------------------------------===//
-/// The return type of functions that do not return normally, that is, a type
-/// with no values.
+/// A type that has no values and can't be constructed.
 ///
-/// Use `Never` as the return type when declaring a closure, function, or
-/// method that unconditionally throws an error, traps, or otherwise does
-/// not terminate.
+/// Use `Never` as the return type of a function
+/// that doesn't return normally --- for example,
+/// because it runs forever or terminates the program.
 ///
+///     // An infinite loop never returns.
+///     func forever() -> Never {
+///         while true {
+///             print("I will print forever.")
+///         }
+///     }
+///
+///     // Calling fatalError(_:file:line:) unconditionally stops the program.
 ///     func crashAndBurn() -> Never {
 ///         fatalError("Something very, very bad happened")
 ///     }
+///
+/// A function that returns `Never` is called a _nonreturning_ function.
+/// Closures, methods, computed properties, and subscripts
+/// can also be nonreturning.
+///
+/// There's no way to create an instance of `Never`;
+/// this characteristic makes it an _uninhabited_ type.
+/// You can use an uninhabited type like `Never`
+/// to represent states in your program
+/// that are impossible to reach during execution.
+/// Swift's type system uses this information ---
+/// for example, to reason about control statements
+/// in cases that are known to be unreachable.
+///
+///     let favoriteNumber: Result<Int, Never> = .success(42)
+///     switch favoriteNumber {
+///     case .success(let value):
+///         print("My favorite number is", value)
+///     }
+///
+/// In the code above,
+/// `favoriteNumber` has a failure type of `Never`,
+/// indicating that it always succeeds.
+/// The switch statement is therefore exhaustive,
+/// even though it doesn't contain a `.failure` case,
+/// because that case could never be reached.
 @frozen
 public enum Never {}