Add more existentials documentation

[ldct]

This PR contains a few changes to add more documentation around existentials. Note that the "Protocols" chapter comes before the "OpaqueTypes" chapter.

• Expand the section Protocols as Types with other examples of using protocols as types
  • Personally I think these are a more common than "as a generic constraint", and hence deserve some elaboration
• Explicitly call the result of protocol composition a Protocol Composition Type.
  • Prior to this PR, the result does not have an explicit name in the Language Guide. Protocol Composition Type is the named used by the Language Reference.
  • The Generics chapter implicitly uses the name Protocol Composition for this. In my mind, this is a short form.
• Explicitly say that existentials can use protocol composition types.
• Delete the "opaque type" section in the protocols chapter. The same material seems to be present in the OpaqueTypes chapter.

[ldct]

ncc1701 is defined on line 233

[ldct]

this protocol is also defined in line 1629 of the "Protocols" chapter

[amartini51]

Thanks for writing this up as a pull request, and in particular thanks for taking the time to include the cross references between running code listings. I'll be out of the office next week for the Thanksgiving holiday, and will continue working with you on these changes when I get back. A few initial notes:

• It would be helpful to understand more detail about the problem in TSPL you’re trying to solve, and why this is the best approach. It looks like you’re adding information about the any P & Q syntax — for example, why a new section, rather than adding to the existing sections?
• The text that was deleted should be kept; it contrasts opaque and boxed types as part of introducing boxed types, with the aim of not requiring the reader to jump forward to the upcoming chapter.
• We’ll need to do some cleanup for style. For example, TSPL specifically avoids the term “existential”, and uses the full words for “enumerations” and “structures” rather than the jargon terms “enum” and “struct”. These are usually pretty easy for me to clean up, but you can also look at the TSPL style guide for more information.

[ldct]

Thanks for the review!

It looks like you’re adding information about the any P & Q syntax

Yes, I was trying to look up what the existentials any syntax supports (i.e. exactly what is legal to put in let x = any ???) and I saw that the section on Boxed Protocol Types is wrong (it says "any before the name of a protocol", which excludes P & Q unless you define "name of a protocol" in a rather unusual (to my mind) way)

The text that was deleted should be kept; it contrasts opaque and boxed types as part of introducing boxed types, with the aim of not requiring the reader to jump forward to the upcoming chapter.

Sure, I can revert this, but it seems strange to me that the Protocols chapter (which comes before the Generics chapter) talks about opaque types.

[ldct]

The language reference calls this a "protocol composition type", but I think the compiler warnings call this a "protocol-constrained type" 🤔

[amartini51]

@ldct Thanks for the revisions, and for your patience — it took longer than I expected to come back to this. I spent some time today look at this again and checking the difference between any P & Q and any (P & Q). Still need to check whether the parentheses would ever be required, or if the compiler is just preserving the “trivia” in the type name as it was spelled in the input.

The bare syntax for existentials was originally going to produce a warning in Swift 6 mode, per SE-0335; that warning was deferred to a future language version. TSPL switched over to the any syntax in #103, which is still the preferred syntax. We shouldn’t add a new section to the guide describing the old syntax. I think the change to SE-0335, removing the warning, might have happened after the PR was merged — and I think you could make a reasonable argument for temporarily adding a section to the reference, describing the old syntax.

The reason for the forward reference from the Protocols chapter to Generics is partly historical, and partly as a way to steer folks away from existentials. There used to be an longer discussion of existentials here, which was replaced in #103 as part of adding any to the docs for SE-0335. The concept of “protocols as types” still needs to be in this chapter, as written, because some of the later sections build on it. But if you (or someone) wanted to pitch a different restructuring on the forums, that’s also possible.

Do you have an example of a compiler warning that refers to “protocol-constrained type”? I don’t think we want to change the TSPL spelling here, but it might be worth working to improve the compiler message, to make it clearer.

I think the next step here is to decide between showing the any (P & Q) or any P & Q syntax and to weave an example of that into the running code samples in the Protocols chapter. I might try to create a fresh PR for that, rather than reverting most of your work here.