[cxx-interop] Add initial documentation for strict memory safety

[egorzhdan]

99% of this document is taken from Gabor's PR: #958.

[j-hui]

I left a bunch of suggested changes.

Some recurring themes:

• We should be consistent about referring to "[the] strict [memory] safety mode" (instead of, e.g., "strict[ly] safe mode.")
• We could be more consistent about code style, e.g., writing T* x instead of T *t.

There's also no documentation about bridging for ptrcheck.h assertions.

Also, I'm wondering how much we should say, "this also works in C by the way." After all, the only C++-specific parts of this document are discussions pertaining to methods, constructors, and this, as well the stuff about std::vector and std::span at the end. I don't think we need to write this to be in C, but perhaps we should at least mention that the parts relevant to C should also work in C (i.e., without C++ interop enabled).

[j-hui]

punctuation nit:

Suggested change

	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)
	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)

[egorzhdan]

This is something new to me, what do --- do?

[j-hui]

It should have been rendered as an emdash, i.e., "—", by Markdown... but now I realize that isn't standard Markdown (though it is supported by some extensions).

I've updated the suggestion to just a unicode emdash.

[j-hui]

Suggested change

	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++ APIs often feature parameters that denote a span of memory.
	For example, some might have two parameters where one points to a memory buffer and the other designates the buffer's size;
	others might use the [`std::span`](https://en.cppreference.com/w/cpp/container/span) type from the C++ standard library.
	When such APIs are appropriately annotated, the Swift compiler can bridge those span-like parameters to Swift's [`Span`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0447-span-access-shared-contiguous-storage.md) and [`MutableSpan`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0467-MutableSpan.md) types, and the user with a safe and convenient interface to those imported APIs.

[j-hui]

We are missing documentation for parameters annotated with __counted_by and __sized_by.

[j-hui]

If that's only coming in a follow-up patch, then maybe we shouldn't even mention the case where we denote a span with two separate parameters, where one is a pointer and the other is a size/length.

[delcypher]

There's no discussion of __counted_by, __counted_by_or_null, __sized_by, or __sized_by_or_null, or __noescape here. I feel like these should be mentioned.

[delcypher]

I don't really know where to fit this in but there are no examples of using __counted_by and friends here. I realize they are not as safe as span but we are providing overloads that are safer that their original counter parts.

[delcypher]

Aren't the safe overloads we provide completely separate from the "strict safe mode"? I've been using them without having this mode on. Introducing the interop makes it seems like it's coupled to "strict safe mode" and I don't think that's the case.

[rapidsna]

+1

[rapidsna]

The content isn't really about strict memory safety mode. I would instead say something like this for the intro:

This document describes safe interoperability between Swift and C/C++ by using annotations to provide missing information in C/C++ types, enabling their safe use.

While optional, the strict memory safe mode introduced in Swift 6.2 can also be used to help find where these annotations should be added.

[egorzhdan]

I rewrote this paragraph to make it a lot more generic.

[rapidsna]

This sounds a bit awkward to me because nothing talked about "StringRef" had a "lifetime dependencies".

[egorzhdan]

Good point, I rephrased it slightly.

[rapidsna]

Did you mean should the "caller" of getFileName normalize the path in this example?

[egorzhdan]

Rephrased this, let me know it it's better now

[rapidsna]

+1

[rapidsna]

The content isn't really about strict memory safety mode. I would instead say something like this for the intro:

This document describes safe interoperability between Swift and C/C++ by using annotations to provide missing information in C/C++ types, enabling their safe use.

While optional, the strict memory safe mode introduced in Swift 6.2 can also be used to help find where these annotations should be added.

[rapidsna]

Suggested title: "Safely mixing C, C++, and Swift" (We need a follow up to add "C" interop part).

[egorzhdan]

We don't really talk about the C part at this point, so I think we can call this "Safely Mixing Swift and C++". I amended the title.