Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more existentials documentation #340

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Conversation

ldct
Copy link
Contributor

@ldct ldct commented Nov 21, 2024

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 ldct changed the title Draft Add more existentials documentation Nov 21, 2024
print("The full name is \(fullyNamed.fullName)")
}

printFullName(ncc1701)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ncc1701 is defined on line 233

@ldct ldct marked this pull request as ready for review November 21, 2024 05:33
An existential can also creating by writing `any` before a protocol composition type (see <doc:Protocols#Protocol-Composition>). This creates a box which holds a structure, class or enum that conforms to all the protocols listed.

```
protocol Named {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@amartini51 amartini51 self-requested a review November 21, 2024 21:44
@amartini51
Copy link
Member

amartini51 commented Nov 23, 2024

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
Copy link
Contributor Author

ldct commented Nov 23, 2024

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.

@@ -1604,9 +1608,9 @@ that tries to adopt `SomeClassOnlyProtocol`.
## Protocol Composition

It can be useful to require a type to conform to multiple protocols at the same time.
You can combine multiple protocols into a single requirement
You can combine multiple protocols into a single *protocol composition type*
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants