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 a forward reference about extensions #128

Merged
merged 2 commits into from
Apr 19, 2023

Conversation

bytedriver
Copy link
Contributor

@bytedriver bytedriver commented Apr 3, 2023

This PR inserts a sentence that explains an extra link about extension in the section Preventing Overrides of the chapter "Inheritance".
"Extension" is mentioned here for the first time. Therefore, it is appropriate to attach a link to it.

To be honest, it is not the first time. You might already find some examples in the Swift Tour, and the chapter "The Basics".
Nonetheless, this time it is mentioned without the link in advance of the chapter "Extensions".
As such, it would be better to have a link.

"Extension" is mentioned here for the first time. Therefore, it is appropriate to attach a link to it.
@amartini51 amartini51 changed the title Add a Link about Extensions Add a forward reference about extensions Apr 13, 2023
@amartini51
Copy link
Collaborator

amartini51 commented Apr 13, 2023

Thanks for looking at this, @bytedriver!

Looking through the places called out above:

  • In the tour, it's an intentional decision that we don't link forward to each topic that's mentioned, so it's correct not to have a link.
  • In The Basics > Integer Conversion we have a forward reference when extensions are discussed as a way to add make additional types convertible to Int
  • In Inheritance > Preventing Overrides, extensions are mentioned by name. I'm not entirely sure that there needs to be a forward reference here, because the discussion is so limited and there's a chapter named Extensions. But if we include one, I'd suggest this wording:

Methods, properties, or subscripts that you add to a class in an extension can also be marked as final within the extension’s definition. For more information, see Extensions.

It might be worth writing up when we do and don't include forward references in Style.md. Most of the wording choices for those references come from Apple or DevPubs style guides, but it might make sense to repeat the typical phrasing in the TSPL style guide.

Refine the description.
@bytedriver
Copy link
Contributor Author

Thank you for reviewing it again @amartini51
I made a little change to the description as you suggested.
👍

@amartini51
Copy link
Collaborator

@krilnon @bjlanier What do you think — is this forward reference needed? Or is the ToC enough?

@amartini51
Copy link
Collaborator

amartini51 commented Apr 19, 2023

This change follows the existing precedent of forward references in the book. Looking at some selected examples:

% git grep --context=2 'doc:[a-zA-Z]*>'

BasicOperators.md-This chapter describes the common operators in Swift.
BasicOperators.md:<doc:AdvancedOperators> covers Swift's advanced operators,
BasicOperators.md-and describes how to define your own custom operators
BasicOperators.md-and implement the standard operators for your own custom types.

CollectionTypes.md-> Note: Swift's array, set, and dictionary types are implemented as *generic collections*.
CollectionTypes.md:> For more about generic types and collections, see <doc:Generics>.

CollectionTypes.md:> For information about conforming to protocols, see <doc:Protocols>.

ErrorHandling.md-For more information about pattern matching,
ErrorHandling.md:see <doc:Patterns>.

Initialization.md:For more information about deinitializers, see <doc:Deinitialization>.

Initialization.md-Classes, however, can inherit from other classes,
Initialization.md:as described in <doc:Inheritance>.

Protocols.md:For information on optional chaining, see <doc:OptionalChaining>.

So there are plenty of places where we say "for information about topic, see Chapter" even when the topic and chapter are the same.

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.

None yet

2 participants