[cxx-interop] Document some caveats of safe interop (#1094)

Some of these like the compiler flag to enable the safe wrappers is not
documented anywhere. Having this documentation in place can help more
people to play around with the feature and report bugs.

Co-authored-by: Gabor Horvath <[email protected]>
Co-authored-by: Joseph Heck <[email protected]>

Author: 3 people

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

@@ -105,6 +105,10 @@ struct SWIFT_NONESCAPABLE StringRef { ... };
 Now the Swift compiler imports `StringRef` as a safe type and no longer
 emits a warning about using an unsafe type.
 
+<div class="info" markdown="1">
+Some containers and protocols do not yet support non-escapable types in Swift 6.2.
+</div>
+
 ### Annotating C++ APIs
 
 Building the code again will emit a new diagnostic for the `fileName` function about
@@ -394,6 +398,13 @@ adding additional annotations to C or C++ APIs will not affect Swift code curren
 relying on the plain interface. Adding additional information may alter the signature
 of any existing safe overload however, since only 1 safe overload per imported function is generated.
 
+<div class="info" markdown="1">
+At the time of writing, the features described in this section
+are behind an experimental feature flag on the Swift 6.2 release branch.
+To enable these features, pass `-enable-experimental-feature SafeInteropWrappers`
+to the Swift compiler.
+</div>
+
 ### Safe Overloads for C++ `std::span`
 
 APIs taking or returning C++'s `std::span` with sufficient lifetime