Apply suggestions from code review

Co-authored-by: John Hui <[email protected]>

Author: egorzhdan

documentation/cxx-interop/safe-interop/index.md

@@ -19,7 +19,7 @@ an opt-in language feature that prevents common memory safety issues by running
 extra compile-time safety checks and emitting diagnostics.
 
 This document describes the way Swift/C++ interoperability works when strict
-safe mode is enabled in Swift.
+safety mode is enabled in Swift.
 
 * * *
 
@@ -42,7 +42,7 @@ Swift provides memory safety with a combination of language affordances and runt
 However, Swift also deliberately includes some unsafe constructs, such as the `UnsafePointer` and `UnsafeMutablePointer`
 types in the standard library.
 In some cases, Swift needs additional information that is not present in the C++ type and API declarations
-to safely interface with them. This document describes how such code needs to be annotated.
+to safely interface with them. This document describes how such code needs to be annotated so that it can be used in strict safety mode.
 
 ### Annotating Foreign Types
 
@@ -52,16 +52,16 @@ pointers will be imported as unsafe (section [Working with C++ references and vi
 explains this in more detail.) Under the strict memory safe mode, the compiler will flip the polarity and
 treat all types that are not known to be safe as unsafe, and will diagnose uses of them. In this section,
 we will show how to annotate unsafe C++ types so that they can be accessed safely and correctly from Swift.
-Note that the features here are agnostic to whether strictly-safe mode is on or off. When the strictly safe
-mode is on, the compiler warnings can serve as a guide to properly annotate C++ types and also help ensure
-that the code doesn't use unsafe APIs anywhere. When the strictly-memory-safe mode is off, it is still
+Note that the features here are agnostic to whether strict safety mode is on or off. When the strict safety
+mode is on, the compiler diagnostics can serve as a guide on how to properly annotate C++ types, and also help ensure
+that the code doesn't use unsafe APIs anywhere. When the strict safety mode is turned off, it is still
 recommended to adopt these annotation wherever appropriate, especially on C++ types that are potentially
-lifetime dependent on other objects.
+dependent on the lifetimes of other objects.
 
-Under strictly-memory-safe mode the built-in integral types like `int`, some standard library types like `std::string`,
-and aggregate types built from other safe types are considered safe. Whereas all other unannotated types
+Under the strict safety mode, built-in numeric types like `int`, some standard library types like `std::string`,
+and aggregate types built from other safe types are considered safe. All other unannotated types
 are considered unsafe. Let's see what happens when we are trying to use an unannotated type in
-strictly-safe mode. Consider the following C++ type and APIs:
+strict safety mode. Consider the following C++ type and APIs:
 
 ```c++
 class StringRef {
@@ -88,13 +88,13 @@ func getFileName(_ path: borrowing std.string) -> StringRef {
 
 Building this code will emit a warning that the `fileName` call is unsafe because
 it references the unsafe type `StringRef`. Swift considers `StringRef` unsafe because
-it has a pointer member. Types like `StringRef` can dangle, so we need to take extra
-care using them, making sure the referenced buffer outlives the `StringRef` object.
+it has a pointer member. Pointers in types like `StringRef` can dangle, so we need to take extra
+care that the buffer they point to outlives the `StringRef` object they are encapsulated by.
 
 Swift's [non-escapable types](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0446-non-escapable.md)
 can also have lifetime dependencies, just like `StringRef`. However, the Swift compiler
 can track these dependencies and enforce safety at compile time. To import `StringRef`
-as a safe type we need to mark it as a non-escapable type, we can annotate the class
+as a safe type, we need to mark it as a non-escapable type by annotating the class
 definition:
 
 ```c++
@@ -107,7 +107,7 @@ emits a warning about using an unsafe type.
 ### Annotating C++ APIs
 
 Building the code again will emit a new diagnostic for the `fileName` function about
-missing lifetime annotations. Functions returning non-escapable types need annotations
+missing lifetime annotations. C and C++ functions that return non-escapable types need annotations
 to describe their lifetime contracts via [lifetimebound](https://clang.llvm.org/docs/AttributeReference.html#id11)
 and [lifetime_capture_by](https://clang.llvm.org/docs/AttributeReference.html#lifetime-capture-by) annotations.
 
@@ -118,7 +118,7 @@ StringRef fileName(const std::string& normalizedPath [[clang::lifetimebound]]);
 Adding this annotation to `fileName` indicates that the returned `StringRef` value has the
 same lifetime as the argument of the `fileName` function.
 
-Building the project again reveals a lifetime error in the Swift function:
+Building the project again reveals a lifetime error in the Swift function that calls `fileName`:
 
 ```swift
 func getFileName(_ path: borrowing std.string) -> StringRef {
@@ -134,7 +134,7 @@ We can fix this error by pushing the task of normalizing a path to the callee:
 
 ```swift
 // Path needs to be normalized.
-func getFileName(_ path: borrowing std.string) -> StringRef {
+func getFileName(_ normalizedPath: borrowing std.string) -> StringRef {
     return fileName(normalizedPath)
 }
 ```
@@ -254,9 +254,9 @@ struct SWIFT_NONESCAPABLE View {
 ```
 
 In this example, the object initialized by the `View` constructor has the same
-lifetime as the input argument of the constructor.
+lifetime as the argument `p` of the constructor.
 
-In case the attribute is after the method signature, the returned object has
+When the attribute is written after the method signature, the returned object has
 the same lifetime as the implicit `this` parameter.
 
 ```c++
@@ -393,6 +393,6 @@ using IntVec = std::vector<int>;
 | `IntSpan changeSpan(IntVec& x [[clang::lifetimebound]]);` | `@lifetime(x) func changeSpan(_ x: borrowing IntVec) -> Span<Int32>` |
 | `IntSpan Owner::getSpan() [[clang::lifetimebound]];`      | `@lifetime(self) func getSpan() -> Span<Int32>`                      |
 
-These transformations only support top level `std::span`s. The compiler
-currently does not transform nested `std::span`s. A `std::span` of a non-const
-type `T` is transformed to `MutableSpan<T>` on the Swift wide.
+These transformations only support top-level `std::span`s. The compiler
+currently does not transform nested `std::span`s. A `std::span<T>` of a non-const
+type `T` is transformed to `MutableSpan<T>` on the Swift side.