Update error handling for typed throws [SE-0413]

[amartini51]

Fixes: rdar://118896654

[amartini51]

Proposal authors, @DougGregor @minuscorp @torstenlehmann, can you please review for technical accuracy?

I've adjusted the framing of when to use typed throws slightly, compared to the SE proposal. The discussion in the SE proposal of implementation details and dependency-free code seems overlap in the sense that the errors aren't part of the code's API to its clients. When vending a throwing API, it's important to use throws(any Error).

I haven't yet added a comparison of throws(T) to rethrows. Do we want to recommend the typed throws spelling in general, or is there still a reason you might want to use rethrows? For example, rethrows still enforces the constraint that errors can come only from called code.

[minuscorp]

It looks good to me 👍

[rebeccateibloom]

Copy edits, as requested in 125975390.

[rebeccateibloom]

Suggested change

	New versions of a library can throw new errors ---
	including libraries used by your dependencies ---
	New versions of a library
	--- including libraries that your dependencies use ---
	can throw new errors,

[rebeccateibloom]

Suggested change

	Throwing an instance `any Error` or another boxed protocol type
	Throwing an instance of `any Error` or another boxed protocol type

[rebeccateibloom]

Suggested change

	Because the errors come only from the library,
	Because the errors come from only the library

[rebeccateibloom]

Suggested change

	and they're always handled within that library.
	they're always handled within that library.

[rebeccateibloom]

Suggested change

	- In code that only throws errors that were thrown elsewhere,
	- In code that throws only errors that were thrown elsewhere,

[rebeccateibloom]

I can't think of an elegant way to make this part of the sentence active ("When ____ uses the errors only within some unit of code"). Hopefully you know the accurate subject that belongs in the blank.

[amartini51]

This is going to be a bit tricky to put into active voice, and not necessarily clearer — this is a good example of an actor that's poorly defined and unimportant. It might be better as "When the errors are contained within some unit of code"? Or to rewrite more aggressively:

When the errors are an implementation detail of some unit of code,
like a library,
and aren't part of the interface to that code.

I'll start with that last rewrite, and we can iterate.

[rebeccateibloom]

Suggested change

	because you write the error type after `throws` --- for example:
	because you write the error type after `throws`, as in this example:

[amartini51]

Rewrote to frame more specifically what the developers should look at the example for.

[rebeccateibloom]

Suggested change

	the `catch` clause can either handle every possible error,
	or it can propagate unhandled errors for some surrounding scope to handle.
	the `catch` clause can either handle every possible error
	or propagate unhandled errors for some surrounding scope to handle.

[rebeccateibloom]

Suggested change

	is nested inside of an exhaustive error handling mechanism,
	is nested inside of an exhaustive error-handling mechanism,

[rebeccateibloom]

I wouldn't include periods because these aren't complete sentences, unless it is your style in TSPL to put periods at the end of all bulleted lists.

Suggested change

	1. Functions that throw any error, marked `throws(any Error)`.
	1. Functions that throw a specific error, marked `throws(MyError)`.
	1. Functions that don't throw, marked `throws(Never)`.
	1. Functions that throw any error, marked `throws(any Error)`
	1. Functions that throw a specific error, marked `throws(MyError)`
	1. Functions that don't throw, marked `throws(Never)`

[amartini51]

@rebeccateibloom Thanks! I've incorporated most of your edits and left queries on a few. There are some that I need to come back to tomorrow still too.

[amartini51]

Moved "In contrast" to the beginning.

[amartini51]

This is going to be a bit tricky to put into active voice, and not necessarily clearer — this is a good example of an actor that's poorly defined and unimportant. It might be better as "When the errors are contained within some unit of code"? Or to rewrite more aggressively:

When the errors are an implementation detail of some unit of code,
like a library,
and aren't part of the interface to that code.

I'll start with that last rewrite, and we can iterate.

[amartini51]

Dropped "generic" to make the xref less specific, and easier to phrase. Started with the half of the comparison that's relevant to the current discussion.

[amartini51]

(As above, line 734)

[amartini51]

The example given here is representative, not exhaustive — and the old wording is somewhat misleading, in suggesting this is the only consequence of being a subtype. There are other things that you can do with a subtype besides just using it where the supertype is expected. With that in mind, do you think "so" is an improvement here? I don't think it matches the meaning.

[rebeccateibloom]

@amartini51 I read through your comments and the latest commit. I marked a few of my past comments/queries as resolved. Thanks for the patient explanations!

[rebeccateibloom]

Looks good to me! Thank you.

[DougGregor]

Thank you for doing this! I left a few suggestions, but this covers all of the major aspects of typed throws that we need to cover.

[DougGregor]

"This approach" starts both this sentence and the prior one. Perhaps use this instead?

Suggested change

	This approach also reflects the fact that errors can change over time.
	It also reflects the fact that errors can change over time.

[DougGregor]

Using "allocate" again here implies the heap. Perhaps somehing like this:

Suggested change

	lets Swift allocate that memory upfront.
	lets Swift avoid heap allocation for errors.

[DougGregor]

I'd like to mention that this is generic code here. We could say "in generic code", or do something like this:

Suggested change

	- In code that throws only errors that were thrown elsewhere,
	like a function that takes a closure argument
	and propagates any errors from that closure.
	- 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.

[DougGregor]

I don't think you have to show multiple catch clauses specifically. It falls out from other sections.

[DougGregor]

I don't think you need to expand on subtyping. However, I would like to describe the Never case, because it's an important part of understanding how typed throws fits in the type system. For example, it could be something like this:

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 cannot throw because it is impossible to create a value of type Never to throw.

[DougGregor]

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).

[DougGregor]

Yes, it is. It's equivalent to throws(any Error).

[DougGregor]

Yes, rethrowing functions are always considered to throw any Error.