Incorporate tech review.

Co-authored-by: Doug Gregor <[email protected]>

Author: amartini51

TSPL.docc/LanguageGuide/ErrorHandling.md

@@ -708,7 +708,7 @@ This approach matches the reality that
 you don't know ahead of time every error that could happen
 while the code is running,
 especially when propagating errors thrown somewhere else.
-This approach also reflects the fact that errors can change over time.
+It also reflects the fact that errors can change over time.
 New versions of a library ---
 including libraries that your dependencies use ---
 can throw new errors,
@@ -729,7 +729,7 @@ in the following special cases:
   requires allocating memory at runtime to store the error.
   In contrast,
   throwing an error of a specific type
-  lets Swift allocate that memory upfront.
+  lets Swift avoid heap allocation for errors.
 
 - When the errors are an implementation detail of some unit of code,
   like a library,
@@ -740,7 +740,7 @@ in the following special cases:
   And because these errors are an implementation detail of the library,
   they're always handled within that library.
 
-- In code that throws only errors that were thrown elsewhere,
+- In code that only propagates errors described by generic parameters,
   like a function that takes a closure argument
   and propagates any errors from that closure.
   For a comparison between propagating a specific error type
@@ -824,7 +824,18 @@ In this code,
 `someThrowingFunction()` propagates any errors that `summarize(_:)` throws.
 The errors from `summarize(_:)` are always `StatisticsError` values,
 which is also a valid error for `someThrowingFunction()` to throw.
-<!-- XXX Expand on subtyping here? -->
+
+Just like you can write a function that never returns
+with a return type of `Never`,
+you can write a function that never throws with `throws(Never)`:
+
+```swift
+func nonThrowingFunction() throws(Never) {
+  // ...
+}
+```
+This function can't throw because
+it's impossible to create a value of type `Never` to throw.
 
 In addition to specifying a function's error type,
 you can also write a specific error type for a `do`-`catch` statement.
@@ -859,8 +870,6 @@ and binds the error to a local constant named `error`.
 Because the `do`-`catch` statement throws `StatisticsError` values,
 `error` is a value of type `StatisticsError`.
 
-<!-- XXX show multiple catch clauses with different patterns? -->
-
 The `catch` clause above uses a `switch` statement
 to match and handle each possible error.
 If you tried to add a new case to `StatisticsError`

TSPL.docc/ReferenceManual/Declarations.md

@@ -1600,6 +1600,12 @@ func f<E: Error>(closure: () throws(E) -> Int) throws(E) -> Int { ... }
 func g(closure: () throws -> Int) rethrows -> Int { ... }
 
 map() from the stdlib is another example
+
+XXX FROM DOUG
+Part of me wants to suggest that this whole section be revised to replace rethrows entirely with the use of generic typed throws, because that's how I expect the language to go over time. Then, rethrows would become more of a historical anecdote. However, that is a lot of work, and perhaps we'll find that rethrows will remain for longer than I expect. If so, I think it's fine to keep this comparison short: take the someFunction example from the beginning of the section and make it generic over the thrown error type, and note that it's providing a more precise guarantee about what errors it rethrows than rethrows does (because rethrows always produces an any Error).
+XXX END FROM DOUG
+
+Filed rdar://128972373
 -->
 
 ### Asynchronous Functions and Methods

TSPL.docc/ReferenceManual/Statements.md

@@ -889,8 +889,6 @@ do throws(<#type#>) {
 }
 ```
 
-<!-- XXX Is "do throws { }" allowed? -->
-
 If the `do` statement includes a `throws` clause,
 the `do` block can throw errors of only the specified *type*.
 The *type* must be
@@ -907,6 +905,7 @@ Swift infers the error type as follows:
 - If the `do` code block contains code that throws
   errors of only a single type
   outside of exhaustive error handling,
+  other than throwing `Never`,
   then Swift infers that the `do` statement throws that concrete error type.
 
 - If the `do` code block contains code that throws

TSPL.docc/ReferenceManual/Types.md

@@ -348,7 +348,6 @@ another function that takes and returns an `Int`.
 
 Function types for functions
 that can throw or rethrow an error must include the `throws` keyword.
-<!-- XXX TR: Confirm rethrowing functions use 'throws' -->
 You can include a type after `throws` in parentheses
 to specify the type of error that the function throws.
 The throw error type must conform to the `Error` protocol.