Add discussion of ~Protocol syntax [SE-0390]

[amartini51]

Fixes: rdar://110848216

[amartini51]

This PR is only part of the updates for SE-0390; tracking docs for syntax like discard and consuming and consume separately. rdar://143719967

[slavapestov]

s/concurrency contexts/isolation domains/

[amartini51]

Changed to "concurrency domains" to match what TSPL currently uses in the Concurrency chapter. We can revisit as part of a pass Holly, Doug, and I want to make over some concurrency terminology.

[xwu]

Suggested change

	- [`BitwiseCopyable`][] for values that con be copied, bit-by-bit.
	- [`BitwiseCopyable`][] for values that can be copied, bit-by-bit.

[amartini51]

Changed

[xwu]

I've always assumed that the Reference Manual is intended to house the more advanced material and that these dedicated sections are supposed to disclose the fundamentals more progressively.

Here, though, "can be copied" is written without explanation while the Reference Manual actually gives a super nice introduction about what that means which could be understood by even a beginner:

By default, Swift uses a set of rules
to automatically manage object lifetime across function calls,
copying values when required.

I wonder if it would be actually appropriate to have (very short) subsections here for each of these protocols to give just a sentence or two like the above and a simple example. A sentence like what I just quoted can be written with a much more approachable voice than what we would want to put (and have put) directly in the protocol documentation.

Other sections (for example, the "Generics" one above) could then refer to this for explanation of Copyable and friends.

[amartini51]

You're correct that the reference is more advanced, and the guide is more approachable. Although in this case, the portion you quoted from the reference is also a little more "tutorial" than usual, because there isn't any discussion of borrowing/consuming in the guide. (Someday maybe there should be though.)

I've expanded this discussion a little, moved Sendable first since people are more likely to encounter it, and I added cross references to later sections that discuss the corresponding concepts. Adding too much here, this early in the book, also risks confusion — most developers can probably skip this section on a first read through TSPL until they actually need to work with (non)sendable or (non)copyable types. That said, there isn't an Advanced Protocols chapter later on, so this is still the right place for the concept of no-requirement protocols and the tilde syntax.

If the issue is that the API references for these protocols are too hard to understand, maybe we need to take some time to improve them. Copyable could probably use a better introduction to what copying means and why you might care, and BitwiseCopyable doesn't even have an API reference (tracked as rdar://128232700).

[ApolloZhu]

I was a little surprised to see this here. After checking Swift Evolution I think this implicit conformance only happens for distributed actor, not other struct/class/etc.? If that's the case, some clarification might be beneficial

[amartini51]

Thanks for calling this out. I re-reviewed the proposals that discuss Codable and either distributed actors or implicit conformance (SE-0302, SE-0336, SE-0344, SE-0413, SE-0428), and I'm pretty sure you're correct. In particular, SE-0302 calls out that Codable, Hashable, and Equatable all require explicit conformance, even when the compiler synthesizes the implementation of that conformance.

Moved this fact to a note box at the end of the section — although I'd also consider having it live just in the API reference for Codable and not in TSPL, until we add a discussion of distributed actors that could mention it. (See also PR #326 with an in-progress draft of a Distributed Actors chapter.)

[ApolloZhu]

... especially since I tried to suppress Codable conformance, but the compiler complains about Type 'Codable' (aka 'Decodable & Encodable') cannot be suppressed

[amartini51]

Changed to "concurrency domains" to match what TSPL currently uses in the Concurrency chapter. We can revisit as part of a pass Holly, Doug, and I want to make over some concurrency terminology.

[amartini51]

Changed

[amartini51]

Thanks for calling this out. I re-reviewed the proposals that discuss Codable and either distributed actors or implicit conformance (SE-0302, SE-0336, SE-0344, SE-0413, SE-0428), and I'm pretty sure you're correct. In particular, SE-0302 calls out that Codable, Hashable, and Equatable all require explicit conformance, even when the compiler synthesizes the implementation of that conformance.

Moved this fact to a note box at the end of the section — although I'd also consider having it live just in the API reference for Codable and not in TSPL, until we add a discussion of distributed actors that could mention it. (See also PR #326 with an in-progress draft of a Distributed Actors chapter.)

[amartini51]

You're correct that the reference is more advanced, and the guide is more approachable. Although in this case, the portion you quoted from the reference is also a little more "tutorial" than usual, because there isn't any discussion of borrowing/consuming in the guide. (Someday maybe there should be though.)

I've expanded this discussion a little, moved Sendable first since people are more likely to encounter it, and I added cross references to later sections that discuss the corresponding concepts. Adding too much here, this early in the book, also risks confusion — most developers can probably skip this section on a first read through TSPL until they actually need to work with (non)sendable or (non)copyable types. That said, there isn't an Advanced Protocols chapter later on, so this is still the right place for the concept of no-requirement protocols and the tilde syntax.

If the issue is that the API references for these protocols are too hard to understand, maybe we need to take some time to improve them. Copyable could probably use a better introduction to what copying means and why you might care, and BitwiseCopyable doesn't even have an API reference (tracked as rdar://128232700).

[amartini51]

Reviewers: Any opinion on this alternative version of the code example?

[xwu]

All protocols have semantic requirements (we have said repeatedly that "protocols are not just bags of syntax"). Perhaps:

Suggested change

	## Protocols That Have Semantic Requirements
	## Protocols That Have Only Semantic Requirements

[xwu]

Suggested change

	not just requirements that you express in code.
	not just requirements that you express in code.

Same comment regarding language here.