Extend the later part of the documentation a bit.

Author: Gabor Horvath

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

@@ -150,9 +150,7 @@ the `SWIFT_NONESCAPABLE` annotation:
 
 ```c++
 struct SWIFT_NONESCAPABLE View {
-    View() : member(nullptr) {}
     View(const int *p) : member(p) {}
-    View(const View&) = default;
 private:
     const int *member;
 };
@@ -162,9 +160,7 @@ Moreover, we can explicitly mark types as `Escapable` using the `SWIFT_ESCAPABLE
 annotation:
 
 ```c++
-struct SWIFT_ESCAPABLE Owner {
-    ...
-}; 
+struct SWIFT_ESCAPABLE Owner { ... }; 
 ```
 
 The main reason for explicitly annotating a type as `SWIFT_ESCAPABLE` is to make sure
@@ -193,28 +189,63 @@ In this example, `MyList<View>` should be imported as `~Escapable` while `MyList
 should be imported as `Escapable`. This can be achieved via conditional escapability
 annotations:
 
-```
+```c++
 template<typename T>
 struct SWIFT_ESCAPABLE_IF(T) MyList {
     ...
 };
 ```
 
+Here, instantiations of `MyList` are imported as `Escapable` when `T` is substituted
+with an `Escapable` type.
+
+The `SWIFT_ESCAPABLE_IF` macro can take multiple template parameters:
+
+```c++
+template<typename F, typename S>
+struct SWIFT_ESCAPABLE_IF(F, S) MyPair {
+    F first;
+    S second;
+};
+```
+
+`MyPair` instantiations are only imported as `Escapable` if both template arguments
+are `Escapable`.
+
+`Escapable` types cannot have `~Escapable` fields. The following code snippet will
+trigger a compiler error:
+
+```c++
+struct SWIFT_NONESCAPABLE View { ... };
+struct SWIFT_ESCAPABLE Owner { 
+    View v;
+}; 
+```
+
+Escapability annotations will not only help the Swift compiler to import C++ types
+safely, it will also help discover missing lifetime annotations as all `~Escapable`
+parameters and return values need to be annotated in an API to make its use safe in
+Swift.
+
 ## Lifetime annotations in detail
 
-The `lifetimebound` attribute can be used to annotate code in various scenarios.
-On a constructor, it describes the lifetime of the created object:
+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:
 
 ```c++
 struct SWIFT_NONESCAPABLE View {
     View(const int *p [[clang::lifetimebound]]) : member(p) {}
-private:
-    const int *member;
+    ...
 };
 ```
 
+In this example, the object initialized by the `View` constructor has the same
+lifetime as the input argument of the constructor.
+
 In case the attribute is after the method signature, the returned object has
-the same lifetime as the `this` object.
+the same lifetime as the implicit `this` parameter.
 
 ```c++
 struct Owner {
@@ -226,27 +257,28 @@ struct Owner {
 };
 ```
 
-In case the attribute is applied to a subset of the formal parameters, the return
+Consider a call site like `View v = o.handOutView()`. The `v` object has the same lifetime
+as `o`.
+
+In case the attribute is applied to a subset of the parameters, the return
 value might depend on the corresponding arguments:
 
 ```c++
-View getView(const Owner& owner [[clang::lifetimebound]]) {
-    return View(&owner.data);
-}
-
-View getViewFromFirst(const Owner& owner [[clang::lifetimebound]], const Owner& owner2) {
-    return View(&owner.data);
-}
-
-View getViewFromEither(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)
         return view1;
     else
         return view2;
 }
 ```
 
-Occasionally, a function might return a non-escapable type that in fact has no dependency on any other values.
+Here, the returned `View`'s lifetime depends on `owner`, `view1`, and `view2` but it cannot
+depend 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.
 Such functions need to be annotated with `SWIFT_RETURNS_INDEPENDENT_VALUE`:
 
@@ -276,17 +308,25 @@ Tags:
 
 Note that APINotes have some limitations around C++, they do not support overloaded functions.
 
-We can use `lifetime_capture_by` annotations for output arguments.
+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`
+annotation to descibe the lifetime of other output values, like output/inout arguments
+or globals.
 
 ```c++
 void copyView(View view1 [[clang::lifetime_capture_by(view2)]], View &view2) {
     view2 = view1;
 }
+```
 
-struct SWIFT_NONESCAPABLE CaptureView {
-    CaptureView() : view(nullptr) {}
-    CaptureView(View p [[clang::lifetimebound]]) : view(p) {}
+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`:
 
+```c++
+struct SWIFT_NONESCAPABLE CaptureView {
     void captureView(View v [[clang::lifetime_capture_by(this)]]) {
         view = v;
     }
@@ -301,11 +341,49 @@ struct SWIFT_NONESCAPABLE CaptureView {
 
 All of the non-escapable inputs 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.
+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.
+
 ## Convenience overloads for annotated spans and pointers
 
+C++ APIs often using standard library types or other constructs like a 
+pointer and a size to represent buffers that have Swift equivalents like
+Swift's `Span` type. These Swift types have additional requirements and
+guarantees. When these properties are properly annotated on the C++ side,
+the Swift compiler can introduce safe convenience functions to make
+interacting with the C++ APIs as effortless as if they were written in Swift.
+
+### C++ span support
+
+APIs taking/returning C++'s `std::span` with sufficient lifetime
+annotations will automatically get overloads taking/returning Swift
+`Span`.
+
+The following table summarizes the generated convenience overloads:
+
+```c++
+using IntSpan = std::span<const int>;
+using IntVec = std::vector<int>;
+```
+
+| C++ API                                                 | Generated Swift overload                                           |
+| ------------------------------------------------------- | ------------------------------------------------------------------ |
+| void takeSpan(IntSpan x [[clang::noescape]]);           | func takeSpan(_ x: Span<Int32>)                                    |
+| IntSpan changeSpan(IntSpan x [[clang::lifetimebound]]); | @lifetime(x) func changeSpan(_ x: Span<Int32>) -> Span<Int32>      |
+| 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, we do not
+transform the nested cases. A `std::span` of a non-const type `T` will
+be transformed to `MutableSpan<T>` on the Swift wide.
+
+### Annotated pointers
+