Address review comments

- replace [[clang::noescape]] syntax with __noescape (etc)
- specify YAML syntax highlighting for YAML code blocks
- consistently use "annotation" in favour of "attribute"
- insert HTML table to enable code block in cells

Author: hnrklssn

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

@@ -111,9 +111,12 @@ Building the code again will emit a new diagnostic for the `fileName` function a
 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#id8)
 and [lifetime_capture_by](https://clang.llvm.org/docs/AttributeReference.html#lifetime-capture-by) annotations.
+Not all versions of C and C++ support the `[[clang::lifetimebound]]` attribute syntax. Convenience macros for
+lifetime annotations using the GNU style attribute syntax are available in the `lifetimebound.h` header, and we'll
+be using them throughout this document.
 
 ```c++
-StringRef fileName(const std::string &normalizedPath [[clang::lifetimebound]]);
+StringRef fileName(const std::string &normalizedPath __lifetimebound);
 ```
 
 Adding this annotation to `fileName` indicates that the returned `StringRef` value has the
@@ -186,7 +189,7 @@ types do not need lifetime annotations.
 
 Escapability annotations can also be attached to types via [API Notes](https://clang.llvm.org/docs/APINotes.html):
 
-```
+```yaml
 Tags:
 - Name: NonEscapableType
   SwiftEscapable: false
@@ -253,7 +256,7 @@ Annotating the parameters of a constructor describes the lifetime of the created
 
 ```c++
 struct SWIFT_NONESCAPABLE View {
-    View(const int *p [[clang::lifetimebound]]) : member(p) {}
+    View(const int *p __lifetimebound) : member(p) {}
     ...
 };
 ```
@@ -268,7 +271,7 @@ the same lifetime as the implicit `this` parameter.
 struct Owner {
     int data;
 
-    View handOutView() const [[clang::lifetimebound]] {
+    View handOutView() const __lifetimebound {
         return View(&data);
     }
 };
@@ -284,10 +287,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]],
+View getOneOfTheViews(const Owner &owner1 __lifetimebound,
                       const Owner &owner2,
-                      View view1 [[clang::lifetimebound]],
-                      View view2 [[clang::lifetimebound]]) {
+                      View view1 __lifetimebound,
+                      View view2 __lifetimebound) {
     if (coinFlip)
         return View(&owner1.data);
     if (coinFlip)
@@ -313,7 +316,7 @@ Notably, the default constructor of a type is always assumed to create an indepe
 
 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.
 
-```
+```yaml
 Tags:
 - Name: MyClass
   Methods:
@@ -335,7 +338,7 @@ annotation to describe the lifetime of other output values, like output/inout ar
 or globals.
 
 ```c++
-void copyView(View view1 [[clang::lifetime_capture_by(view2)]], View &view2) {
+void copyView(View view1 __lifetime_capture_by(view2), View &view2) {
     view2 = view1;
 }
 ```
@@ -351,11 +354,11 @@ private:
     View containedView;
 
 public:
-    void captureView(View v [[clang::lifetime_capture_by(this)]]) {
+    void captureView(View v __lifetime_capture_by(this)) {
         containedView = v;
     }
 
-    void handOut(View &v) const [[clang::lifetime_capture_by(v)]] {
+    void handOut(View &v) const __lifetime_capture_by(v) {
        v = containedView; 
     }
 };
@@ -366,7 +369,7 @@ 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]]);
+void is_palindrome(std::span<int> s __noescape);
 ```
 
 The lifetime annotations presented in this sections are powerful,
@@ -406,10 +409,10 @@ 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>`                      |
+| `void takeSpan(IntSpan x __noescape);`           | `func takeSpan(_ x: Span<Int32>)`                                    |
+| `IntSpan changeSpan(IntSpan x __lifetimebound);` | `@lifetime(x) func changeSpan(_ x: Span<Int32>) -> Span<Int32>`      |
+| `IntSpan changeSpan(IntVec &x __lifetimebound);` | `@lifetime(x) func changeSpan(_ x: borrowing IntVec) -> Span<Int32>` |
+| `IntSpan Owner::getSpan() __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<T>` of a non-const
@@ -420,32 +423,33 @@ type `T` is transformed to `MutableSpan<T>` on the Swift side.
 If an API uses raw pointers rather than `std::span` - perhaps because it's written in C or Objective-C,
 or because it's an older C++ API that doesn't want to break backwards compatibility -
 it can still receive the same interop safety as `std::span`. This added bounds safety doesn't break
-source compatiblity, nor does it affect ABI. Instead it leverages bounds attributes to express the
+source compatiblity, nor does it affect ABI. Instead it leverages bounds annotations to express the
 pointer bounds in terms of other parameters in the function signature.
 
-#### Annotating Pointers with Bounds Attributes
+#### Annotating Pointers with Bounds Annotations
 
-The most common bounds attribute is `__counted_by`. You can apply `__counted_by` to pointer parameters
+The most common bounds annotation is `__counted_by`. You can apply `__counted_by` to pointer parameters
 and return values to indicate the number of elements that the pointer points to, like this:
 
 ```c
-int calculate_sum(const int * __counted_by(len) values [[clang::noescape]], int len);
+int calculate_sum(const int * __counted_by(len) values __noescape, int len);
 ```
 
-In this example the function signature on the C side hasn't changed, but the `__counted_by(len)`
+In this example, the function signature on the C side hasn't changed, but the `__counted_by(len)`
 annotation communicates that the `values` and `len` parameters are related - specifically, `values`
 should point to a buffer of at least `len` `int` values. When you annotate a function with a bounds
-attribute like this, the compiler will generate a bounds safe overload: in addition to the imported
+annotation like this, the compiler will generate a bounds safe overload: in addition to the imported
 `func calculate_sum(_ values: UnsafePointer<CInt>, _ len: CInt) -> CInt` signature, you will also
 get the an overload with the `func calculate_sum(_ values: Span<CInt>) -> CInt` signature.
+Note that, like for `std::span`, the `__noescape` annotation is necessary to get a safe wrapper using `Span`.
 This signature is not only more ergonomic to work with - since the generated overload does the unpacking
 of base pointer and count for you - but it's also bounds safe. For example, if your API contains parameters
 that share a count, the bounds safe overload will check that they all correspond.
 
 ```c
-void sum_vectors(const int * __counted_by(len) a [[clang::noescape]],
-                 const int * __counted_by(len) b [[clang::noescape]],
-                 int * __counted_by(len) out [[clang::noescape]],
+void sum_vectors(const int * __counted_by(len) a __noescape,
+                 const int * __counted_by(len) b __noescape,
+                 int * __counted_by(len) out __noescape,
                  int len);
 ```
 This safe overload will trap if `a.count != b.count || b.count != out.count`:
@@ -455,13 +459,13 @@ func sum_vectors(_ a: Span<CInt>,
                  _ out: MutableSpan<CInt>)
 ```
 
-If one of the `Span` parameters is larger than the others and you intentionally want to use
+If the count of the `Span` parameters is larger than the C function expects and you intentionally want to use
 only a part of it, you can create a slice using `extracting(_:)`.
 
 If your API has more complex bounds you can express those with an arithmetic expression, like so:
 
 ```c
-int transpose_matrix(int * __counted_by(columns * rows) values [[clang::noescape]], int columns, int rows);
+int transpose_matrix(int * __counted_by(columns * rows) values __noescape, int columns, int rows);
 ```
 
 In this case the `columns` and `rows` parameters can't be elided:
@@ -473,35 +477,94 @@ Instead a bounds check is inserted to verify that `columns * rows == values.coun
 
 When your C/C++ API uses opaque pointers, void pointers or otherwise pointers to unsized types,
 the buffer size can't be described in terms of the number of elements. Instead you can annotate
-these pointers with `__sized_by`. This bounds attribute behaves like `__counted_by`, but takes
+these pointers with `__sized_by`. This bounds annotation behaves like `__counted_by`, but takes
 a parameter describing the *number of bytes* in the buffer rather than the *number of elements*.
 Where `__counted_by` maps to `Span<T>`, `__sized_by` will map to
 `RawSpan` instead.
 
 You can access the `__counted_by` and `__sized_by` macro definitions by including the `ptrcheck.h` header.
 For more information about these annotations, see Clang's [bounds safety documentation](https://clang.llvm.org/docs/BoundsSafety.html).
-If the C code base is compiled with `-fbounds-safety` bounds safety is enforced on the C side as well -
+If the C code base is compiled with `-fbounds-safety`, bounds safety is enforced on the C side as well -
 otherwise it is only enforced at the interop boundary.
 
 #### Lifetime Annotations for Pointers
 
 Like with `std::span`, pointers with bounds annotations can have their safe overloads map to
-`Span`/`MutableSpan` when annotated with the appropriate lifetime annotations. Not all C versions
-support the `[[clang::noescape]]` attribute syntax, so convenience macros for lifetime attributes
-using the GNU style syntax are available in the `lifetimebound.h` header. Unlike `std::span`, pointers
-with bounds annotations also get a bounds safe overload when they lack lifetime annotations:
+`Span`/`MutableSpan` when annotated with the appropriate lifetime annotations from the `lifetimebound.h` header.
+Unlike `std::span`, pointers with bounds annotations also get a bounds safe overload when they lack lifetime annotations:
+
+<table>
+<tr><td> C API </td> <td> Generated Swift overload </td></tr>
 
+<tr>
+<td markdown=1>
 ```c
-#include <ptrcheck.h>
-#include <lifetimebound.h>
+void
+take_ptr_lifetime(
+  const int * __counted_by(len) x __noescape,
+  int len);
 ```
+</td>
+<td markdown=1>
+```swift
+func take_ptr_lifetime(_ x: Span<Int32>)
+```
+</td>
+</tr>
 
-| C API                                                                                                          | Generated Swift overload                                                                           |
-| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `void take_ptr_lifetime(const int * __counted_by(len) x __noescape, int len);`                                 | `func take_ptr_lifetime(_ x: Span<Int32>)`                                                         |
-| `const int * __counted_by(len) change_ptr_lifetime(const int * __counted_by(len) x __lifetimebound, int len);` | `@lifetime(x) func change_ptr_lifetime(_ x: Span<Int32>) -> Span<Int32>`                           |
-| `void take_ptr(const int * __counted_by(len) x, int len);`                                                     | `func take_ptr(_ x: UnsafeBufferPointer<Int32>)`                                                   |
-| `const int * __counted_by(len) change_ptr(const int * __counted_by(len) x, int len);`                          | `@lifetime(x) func change_ptr(_ x: UnsafeBufferPointer<Int32>) -> UnsafeBufferPointer<Int32>`      |
+<tr>
+<td markdown=1>
+```c
+const int * __counted_by(len)
+change_ptr_lifetime(
+  const int * __counted_by(len) x __lifetimebound,
+  int len);
+```
+</td>
+<td markdown=1>
+```swift
+@lifetime(x)
+func change_ptr_lifetime(_ x: Span<Int32>)
+  -> Span<Int32>
+```
+</td>
+</tr>
+
+<tr>
+<td markdown=1>
+```c
+void
+take_ptr(
+  const int * __counted_by(len) x,
+  int len);
+```
+</td>
+<td markdown=1>
+```swift
+func take_ptr(_ x: UnsafeBufferPointer<Int32>)
+```
+</td>
+</tr>
+
+<tr>
+<td markdown=1>
+```c
+const int * __counted_by(len)
+change_ptr(
+  const int * __counted_by(len) x,
+  int len);
+```
+</td>
+<td markdown=1>
+```swift
+@lifetime(x)
+func change_ptr(_ x: UnsafeBufferPointer<Int32>)
+  -> UnsafeBufferPointer<Int32>
+```
+</td>
+</tr>
+
+</table>
 
 The `UnsafeBufferPointer` overloads provide the same bounds safety as their `Span` equvalents
 (NB: `UnsafeBufferPointer` is not bounds checked on memory access in release builds, but the generated
@@ -516,14 +579,14 @@ adding any bounds or lifetime annotations.
 
 #### Bounds Annotations using API Notes
 
-In cases where you don't want to modify the imported headers, bounds attributes can be applied using API Notes.
+In cases where you don't want to modify the imported headers, bounds annotations can be applied using API Notes.
 Given the following header:
 ```c
 void foo(int *p, int len);
 void *bar(int size);
 ```
 We can provide bounds annotations in our API note file like this:
-```
+```yaml
 Functions:
   - Name:              foo
     Parameters:
@@ -538,12 +601,13 @@ Functions:
 ```
 
 #### Limitations
-Bounds attributes are not supported for nested pointers: only the outermost pointer can be transformed.
+Bounds annotations are not supported for nested pointers: only the outermost pointer can be transformed.
 
-`lifetime_capture_by` is currently not taken into account when generating safe overloads.
+[`lifetime_capture_by`](https://clang.llvm.org/docs/AttributeReference.html#lifetime-capture-by)
+is currently not taken into account when generating safe overloads.
 
-Bounds attributes on global variables or struct fields are ignored: only parameters and return values
+Bounds annotations on global variables or struct fields are ignored: only parameters and return values
 are considered.
 
-Bounds attributes, while supported in Objective-C code bases, are not currently supported in Objective-C
+Bounds annotations, while supported in Objective-C code bases, are not currently supported in Objective-C
 class method signatures.