From 20a795e6c6be5b27e16df257f104f5f26ab730e9 Mon Sep 17 00:00:00 2001
From: Clar Charr <clar@charr.xyz>
Date: Sun, 15 Apr 2018 17:07:39 -0400
Subject: [PATCH 1/2] Mention Result<!, E> in never docs.
---
src/libstd/primitive_docs.rs | 52 ++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index ce4bbfffc2e47..8905f7c9e1605 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -112,6 +112,8 @@ mod prim_bool { }
///
/// # `!` and generics
///
+/// ## Infalliable errors
+///
/// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`]
/// trait:
///
@@ -140,9 +142,59 @@ mod prim_bool { }
/// [`Ok`] variant. This illustrates another behaviour of `!` - it can be used to "delete" certain
/// enum variants from generic types like `Result`.
///
+/// ## Infinite loops
+///
+/// While [`Result<T, !>`] is very useful for removing errors, `!` can also be used to removed
+/// successes as well. If we think of [`Result<T, !>`] as "if this function returns, it has not
+/// errored," we get a very intuitive idea of [`Result<!, E>`] as well: if the function returns, it
+/// *has* errored.
+///
+/// For example, consider the case of a simple web server, which can be simplified to:
+///
+/// ```ignore (hypothetical-example)
+/// loop {
+/// let (client, request) = get_request().expect("disconnected");
+/// let response = request.process();
+/// response.send(client);
+/// }
+/// ```
+///
+/// Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection.
+/// Instead, we'd like to keep track of this error, like this:
+///
+/// ```ignore (hypothetical-example)
+/// loop {
+/// match get_request() {
+/// Err(err) => break err,
+/// Ok((client, request)) => {
+/// let response = request.process();
+/// response.send(client);
+/// },
+/// }
+/// }
+/// ```
+///
+/// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it
+/// might be intuitive to simply return the error, we might want to wrap it in a [`Result<!, E>`]
+/// instead:
+///
+/// ```ignore (hypothetical-example)
+/// fn server_loop() -> Result<!, ConnectionError> {
+/// Ok(loop {
+/// let (client, request) = get_request()?;
+/// let response = request.process();
+/// response.send(client);
+/// })
+/// }
+/// ```
+///
+/// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop
+/// ever stops, it means that an error occurred.
+///
/// [`String::from_str`]: str/trait.FromStr.html#tymethod.from_str
/// [`Result<String, !>`]: result/enum.Result.html
/// [`Result<T, !>`]: result/enum.Result.html
+/// [`Result<!, E>`]: result/enum.Result.html
/// [`Ok`]: result/enum.Result.html#variant.Ok
/// [`String`]: string/struct.String.html
/// [`Err`]: result/enum.Result.html#variant.Err
From fc6d6c98dedca297c09016615011bee448e5e468 Mon Sep 17 00:00:00 2001
From: Clar Charr <clar@charr.xyz>
Date: Fri, 4 May 2018 21:37:28 -0400
Subject: [PATCH 2/2] Fixed typos
---
src/libstd/primitive_docs.rs | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index 8905f7c9e1605..49344cab1dd26 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -112,7 +112,7 @@ mod prim_bool { }
///
/// # `!` and generics
///
-/// ## Infalliable errors
+/// ## Infallible errors
///
/// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`]
/// trait:
@@ -144,7 +144,7 @@ mod prim_bool { }
///
/// ## Infinite loops
///
-/// While [`Result<T, !>`] is very useful for removing errors, `!` can also be used to removed
+/// While [`Result<T, !>`] is very useful for removing errors, `!` can also be used to remove
/// successes as well. If we think of [`Result<T, !>`] as "if this function returns, it has not
/// errored," we get a very intuitive idea of [`Result<!, E>`] as well: if the function returns, it
/// *has* errored.
@@ -175,21 +175,22 @@ mod prim_bool { }
/// ```
///
/// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it
-/// might be intuitive to simply return the error, we might want to wrap it in a [`Result<!, E>`]
+/// might be intuitive to simply return the error, we might want to wrap it in a [`Result<!, E>`]
/// instead:
///
/// ```ignore (hypothetical-example)
/// fn server_loop() -> Result<!, ConnectionError> {
-/// Ok(loop {
+/// loop {
/// let (client, request) = get_request()?;
/// let response = request.process();
/// response.send(client);
-/// })
+/// }
/// }
/// ```
///
/// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop
-/// ever stops, it means that an error occurred.
+/// ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok`
+/// because `!` coerces to `Result<!, ConnectionError>` automatically.
///
/// [`String::from_str`]: str/trait.FromStr.html#tymethod.from_str
/// [`Result<String, !>`]: result/enum.Result.html