Updates for `package` [SE-0386]

[tadbyt]

Update The Swift Programming Language to match the language changes implemented by SE-0386. Five subsections in the document were identified as being impacted by the implementation of SE-0386.

Guide > Access Control

Modules and Source Files

Change the title to Modules, Source Files and Packages.

Replace the first paragraph with: Swift’s access control model is based on the concepts of modules, and source files and packages.

Add the following two paragraphs to the end of the subsection:

A package is a reusable component of Swift, Objective-C, Objective-C++, C or C++ code that developers use in their projects. A package bundles source files, binaries and resources in a way that’s easy to use in an app’s project. A package is comprised of a set of one or more interrelated modules.

Unlike many other languages, the linkages from packages to their constituent modules as well as from modules to their constituent source files are defined outside of the Swift language itself, in the context of the applicable development environment.

Make the first instance of package in the first of the added paragraphs a hyperlink to https://developer.apple.com/documentation/xcode/swift-packages

Access Levels

Replace the first paragraph with:

Swift provides six different access levels for entities within your code. These access levels are relative to the source file in which an entity is defined, to the module that source file belongs to and to the package that the module belongs to.

Add the following as the second bullet in the subsequent list:

• Package access enables entities to be used within any source file from their defining package, but not in any source file outside of that package. You typically use internal access when defining an app’s or a framework’s internal structure that spans multiple modules.

Append the following to the end of the next bullet: contained within a single module

Access Control Syntax

In the first paragraph, insert package (followed by a comma) between public and internal.

In the list of classes, insert the following after the public class: package class SomePackageClass {}

In the list of constants and variables, insert the following after the public var: package let somePackageConstant = 0

Reference > Lexical Structure

Keywords and Punctuation

In the list of keywords reserved in particular contexts, insert package (followed by a comma) between override and postfix.

Reference > Declarations

Access Control Levels

In the list given after the first paragraph, insert the following between the entries for public and internal:

package Apply this modifier to a declaration to indicate the declaration can be accessed only by code in the same package as the declaration.

In the list of access-level-modifiers, insert the following after the entry for internal and internal(set):

access-level-modifier → package | package ( set )

rdar://117171554

[amartini51]

Closed the above bugs and copied their content into this bug, with minor reformatting, because we would do all of this work at the same time. It wouldn't make sense, for example, to update only one section of the reference.

@tadbyt How would you like me to credit you in the Co-authored-by: trailer when I commit your suggested initial changes? Normally Git uses name + email, but all I have is your GitHub username. I can write Co-authored-by: @tadbyt but I'm not sure if GitHub will understand that and correctly display you as a contributor. If you have no preference, that's fine too.

[tadbyt]

Also, update the Getters and Setters subsection to include package(set).

https://docs.swift.org/swift-book/documentation/the-swift-programming-language/accesscontrol#Getters-and-Setters