Apply suggestions from code review

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

Author: egorzhdan

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

@@ -49,8 +49,9 @@ to safely interface with them. This document describes how such code needs to be
 Types imported from C++ are considered foreign to Swift. Normally, most C++ types are imported into Swift
 without any restriction. However, a small set of C++ APIs e.g. pointers/references and methods returning
 pointers will be imported as unsafe (section [Working with C++ references and view types in Swift](https://www.swift.org/documentation/cxx-interop/#working-with-c-references-and-view-types-in-swift)
-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,
+explains this in more detail.) Under the strict memory safety mode, the compiler will flip the polarity of its safety assumptions.
+It will treat all types that are not known to be safe as unsafe, and emit diagnostics for usage of unsafe types without the `unsafe` keyword.
+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 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
@@ -60,7 +61,9 @@ dependent on the lifetimes of other objects.
 
 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
+are considered unsafe.
+
+Let's see what happens when we are trying to use an unannotated type in
 strict safety mode. Consider the following C++ type and APIs:
 
 ```c++
@@ -108,7 +111,7 @@ emits a warning about using an unsafe type.
 
 Building the code again will emit a new diagnostic for the `fileName` function about
 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)
+to describe their lifetime contracts via [lifetimebound](https://clang.llvm.org/docs/AttributeReference.html#id8)
 and [lifetime_capture_by](https://clang.llvm.org/docs/AttributeReference.html#lifetime-capture-by) annotations.
 
 ```c++
@@ -139,7 +142,7 @@ func getFileName(_ normalizedPath: borrowing std.string) -> StringRef {
 }
 ```
 
-Or we could return an `Escapable` value like `std.string` instead of a dangling `StringRef`:
+Or we could construct and return an `Escapable` value like `std.string` instead of a dangling `StringRef`:
 
 ```swift
 func getFileName(_ path: borrowing std.string) -> std.string {
@@ -149,8 +152,8 @@ func getFileName(_ path: borrowing std.string) -> std.string {
 }
 ```
 
-After annotating the C++ code, the Swift compiler can enforce the lifetime
-contracts helping us to write code that is free of memory safety errors.
+After annotating the C++ code, the Swift compiler can enforce those lifetime
+contracts and help us to write code that is free of memory safety errors.
 
 ## Escapability Annotations in Detail
 
@@ -176,10 +179,10 @@ struct SWIFT_ESCAPABLE Owner { ... };
 ```
 
 The main reason for explicitly annotating a type as `SWIFT_ESCAPABLE` is to make sure
-it is considered as a safe type when used from Swift. Functions returning escapable
+it is considered a safe type when used from Swift. Functions returning escapable
 types do not need lifetime annotations.
 
-Escapability annotations can also be attached to types via API Notes:
+Escapability annotations can also be attached to types via [API Notes](https://clang.llvm.org/docs/APINotes.html):
 
 ```
 Tags:
@@ -244,7 +247,7 @@ Swift.
 The `lifetimebound` attribute on a function parameter or implicit object parameter
 indicates that the returned object's lifetime could end when any of the `lifetimebound`
 annotated parameters' lifetime ended.
-This annotation a constructor describes the lifetime of the created object:
+Annotating the parameters of a constructor describes the lifetime of the created object:
 
 ```c++
 struct SWIFT_NONESCAPABLE View {
@@ -276,8 +279,10 @@ In case the attribute is applied to a subset of the parameters, the return
 value might depend on the corresponding arguments:
 
 ```c++
-View getOneOfTheViews(const Owner& owner1 [[clang::lifetimebound]], const Owner& owner2
-    View view1 [[clang::lifetimebound]], View view2 [[clang::lifetimebound]]) {
+View getOneOfTheViews(const Owner& owner1 [[clang::lifetimebound]],
+                      const Owner& owner2,
+                      View view1 [[clang::lifetimebound]],
+                      View view2 [[clang::lifetimebound]]) {
     if (coinFlip)
         return View(&owner1.data);
     if (coinFlip)
@@ -287,8 +292,7 @@ View getOneOfTheViews(const Owner& owner1 [[clang::lifetimebound]], const Owner&
 }
 ```
 
-Here, the returned `View`'s lifetime depends on `owner`, `view1`, and `view2` but it cannot
-depend on `owner2`.
+Here, the returned `View`'s lifetime depends on `owner`, `view1`, and `view2` but not on `owner2`.
 
 Occasionally, a function might return a non-escapable type that has no dependency on any other values.
 These types might point to static data or might represent an empty sequence or lack of data.
@@ -302,7 +306,7 @@ View returnsEmpty() SWIFT_RETURNS_INDEPENDENT_VALUE {
 
 Notably, the default constructor of a type is always assumed to create an independent value.
 
-We can also annotate `lifetimebound` APIs via APINotes. The `-1` index represents the `this` position.
+We can also attach `lifetimebound` annotations to C and C++ APIs using [API Notes](https://clang.llvm.org/docs/APINotes.html). The `-1` index represents the `this` position.
 
 ```
 Tags:
@@ -321,7 +325,7 @@ Tags:
 Note that APINotes have some limitations around C++, they do not support overloaded functions.
 
 While `lifetimebound` always describes the lifetime dependencies of the return value (or
-the constructed object in case of constructors), we can use can use `lifetime_capture_by`
+the constructed object in case of constructors), we can use can use the [`lifetime_capture_by`](https://clang.llvm.org/docs/AttributeReference.html#lifetime-capture-by)
 annotation to describe the lifetime of other output values, like output/inout arguments
 or globals.
 
@@ -334,8 +338,8 @@ void copyView(View view1 [[clang::lifetime_capture_by(view2)]], View &view2) {
 In this example, `view2` will have get all of the lifetime dependencies of `view1`
 after a call to `copyView`. a
 
-We can annotate dependency captured by the implicit `this` object, or
-an inout argument capturing `this`:
+We can use this annotation to specify that a parameter's lifetime dependencies are captured by the implicit `this` object, or
+conversely, that an inout argument captures the lifetime dependencies of `this`:
 
 ```c++
 struct SWIFT_NONESCAPABLE CaptureView {
@@ -351,18 +355,19 @@ struct SWIFT_NONESCAPABLE CaptureView {
 };
 ```
 
-All of the non-escapable inputs need lifetime annotations for a function to be
+All of the non-escapable arguments need lifetime annotations for a function to be
 considered safe. If an input never escapes from the called function we can use
 the `noescape` annotation:
 
 ```c++
 void is_palindrome(std::span<int> s [[clang::noescape]]);
 ```
 
-While the annotations in this section are powerful, they cannot express all of
-the lifetime contracts. APIs with inexpressible contracts can be used from Swift,
-but they are imported as unsafe APIs and need extra care from the developers
-to manually guarantee safety.
+The lifetime annotations presented in this sections are powerful,
+but there are still lifetime contracts that they cannot express.
+APIs with such contracts can still be used from Swift,
+but they are imported as unsafe APIs, so that developers are aware
+that they need to take extra care when using these APIs to avoid memory safety violations.
 
 ## Convenience Overloads for Annotated Spans and Pointers