Update 'Member import visibility' proposal:

- Re-organize the Motivation section for clarity
- Correct the explanation of Clang module re-exports

Author: tshortli

proposals/NNNN-member-import-visibility.md

@@ -24,20 +24,7 @@ This proposal unifies the behavior of name lookup by changing the rules to bring
 
 ## Motivation
 
-Suppose you have a program depends on a library named `RecipeKit`. The library interface looks like this:
-
-```swift
-// RecipeKit interface
-
-public struct Recipe { /*...*/ }
-
-extension String {
-  /// Returns the recipe represented by this string.
-  public func parse() -> Recipe?
-}
-```
-
-To start, your program contains a single source file `main.swift` that imports `RecipeKit`:
+Suppose you have an app that depends on an external library named `RecipeKit`. To start, your app contains a single source file `main.swift` that imports `RecipeKit`:
 
 ```swift
 // main.swift
@@ -46,20 +33,20 @@ import RecipeKit
 let recipe = "2 slices of bread, 1.5 tbs peanut butter".parse()
 ```
 
-Later, you decide to integrate with a new library named `GroceryKit` which happens to also declares its own `parse()` method in an extension on `String`:
+The interface of `RecipeKit` looks like this:
 
 ```swift
-// GroceryKit interface
-public struct GroceryList { /*...*/ }
+// RecipeKit interface
+
+public struct Recipe { /*...*/ }
 
 extension String {
-  /// Returns the grocery list represented by this string.
-  public func parse() -> GroceryList?
+  /// Returns the recipe represented by this string.
+  public func parse() -> Recipe?
 }
-
 ```
 
-You add a second file that imports `GroceryKit`:
+Later, you decide to integrate with a new library named `GroceryKit`. You add a second file to your app that imports `GroceryKit`:
 
 ```swift
 // Groceries.swift
@@ -69,7 +56,7 @@ var groceries = GroceryList()
 // ...
 ```
 
-Surprisingly, now that `GroceryKit` is a transitive dependency of `main.swift`, there's a new compilation error:
+Surprisingly, after adding the second file there's now a compilation error in `main.swift`:
 
 ```swift
 // main.swift
@@ -79,12 +66,26 @@ let recipe = "2 slices of bread, 1.5 tbs peanut butter".parse()
 // error: Ambiguous use of 'parse()'
 ```
 
-Before the new file was added, `parse()` could only refer to the extension member from `RecipeKit`. Now that it might also reference the extension member in `GroceryKit` the compiler considers the use of `parse()` to be ambiguous. To resolve the ambiguity, the developer must add a type annotation to the declaration of the variable `recipe` to give the compiler the additional context it needs to disambiguate:
+The call to `parse()` is now ambiguous because `GroceryKit` happens to also declares its own `parse()` method in an extension on `String`:
+
+```swift
+// GroceryKit interface
+public struct GroceryList { /*...*/ }
+
+extension String {
+  /// Returns the grocery list represented by this string.
+  public func parse() -> GroceryList?
+}
+
+```
+
+Even though `GroceryKit` was not imported in `main.swift`, its `parse()` method is now a candidate in that file. To resolve the ambiguity, you can add a type annotation to the declaration of the variable `recipe` to give the compiler the additional context it needs to disambiguate the call:
+
 ```swift
 let recipe: Recipe = "2 slices of bread, 1.5 tbs peanut butter".parse() // OK
 ```
 
-This example demonstrates why "leaky" member visibility is undesirable. Although the fix for the new error is relatively simple in this code, providing disambiguation context to the compiler is not always so straightforward. Additionally, the fact that some declarations from `GroceryKit` are now visible in `main.swift` contradicts developer expectations, since visibility rules for top level declarations do not behave this way. This idiosyncrasy in Swift's import visibility rules harms local reasoning and results in confusing errors.
+This example demonstrates why Swift's existing "leaky" member visibility is undesirable. Although the fix for the new error is relatively simple in this code, providing disambiguation context to the compiler is not always so straightforward. Additionally, the fact that some declarations from `GroceryKit` are now visible in `main.swift` contradicts developer expectations, since visibility rules for top level declarations do not behave this way. This idiosyncrasy in Swift's import visibility rules harms local reasoning and results in confusing errors.
 
 ## Proposed solution
 
@@ -98,14 +99,9 @@ A reference to a member in a source file will only be accepted if that member is
 - The module is directly imported from the bridging header.
 - The module is in the set of modules that is re-exported by any module that is either directly imported in the file or directly imported in the bridging header.
 
-A module is considered to be re-exported by the module that imports it when any of the following statements are true:
-
-- The associated import statement has the `@_exported` attribute.
-- The exporting module is a clang module.
-
-Re-exports are transitive, so if module `A` re-exports module `B`, and module `B` re-exports module `C`, then declarations from `A`, `B`, and `C` are all in scope in a file that directly imports `A`.
+A Swift module re-exports any modules that have been imported using the `@_exported` attribute. Clang modules list the modules that they re-export in their modulemap files, and it is common for a Clang module to re-export every module it imports using `export *`. Re-exports are also transitive, so if module `A` re-exports module `B`, and module `B` re-exports module `C`, then declarations from `A`, `B`, and `C` are all in scope in a file that only imports `A` directly.
 
-Note that there are some imports that are added to every source file implicitly by the compiler for normal programs. The implicitly imported modules include the standard library and the module being compiled. As a subtle consequence of the implicit import of the current module, any module that is `@_exported` in any source file of the module is also part of the set of re-exported modules that are visible in the file.
+Note that there are some imports that are added to every source file implicitly by the compiler for normal programs. The implicitly imported modules include the standard library and the module being compiled. As a subtle consequence implicitly importing the current module, any module that is `@_exported` in any source file is also considered visible in every other source file because it is a re-export of a direct import.
 
 ## Source compatibility