Merge pull request #62412 from hyp/eng/import_ref_docx2

[docs][interop] give a more specific example of how to use import_ref…

Author: hyp

docs/CppInteroperability/UserManual.md

@@ -6,6 +6,35 @@ The following document explains how C++ APIs are imported into Swift and is targ
 
 Reference types have reference semantics and object identity. A reference type is a pointer (or “reference”) to some object which means there is a layer of indirection. When a reference type is copied, the pointer’s value is copied rather than the object’s storage. This means reference types can be used to represent non-copyable types in C++. Any C++ APIs that use reference types must have at least one layer of indirection to the type (a pointer or reference). Currently reference types must be immortal (never deallocated) or have manually managed lifetimes. You can specify a type has reference semantics by using the `import_reference` swift attribute.
 
+### Importing custom reference counted types into Swift
+
+C++ types that have their own reference count and custom retain/release operations
+can be bridged over as reference types into Swift. Swift's automatic reference counting (ARC)
+will automatically retain and release them using their C++ reference counting operations.
+
+The `import_reference` swift attribute can be applied with the appropriate `retain` and `release` attributes
+to import a type with such semantics as a reference type into Swift.
+The example below illustrates how this can be done for the C++ `MyReferenceObject` class:
+
+```c++
+#define SWIFT_CXX_REF_MYREFOBJECT   \
+    __attribute__((swift_attr("import_reference")))   \
+    __attribute__((swift_attr("retain:incRef")))   \
+    __attribute__((swift_attr("release:decRef")))
+
+class SWIFT_CXX_REF_MYREFOBJECT MyReferenceObject {
+private:
+  int referenceCount; // the custom reference count.
+};
+
+/// Increment the reference count for the given object.
+void incRef(MyReferenceObject *object);
+
+/// Decrement the reference count for the given object. When it reaches zero,
+/// the object is deallocated.
+void decRef(MyReferenceObject *object);
+```
+
 ## Owned Types
 
 Owned types “own” some storage which can be copied and destroyed. An owned type must be copyable and destructible. The copy constructor must copy any storage that is owned by the type and the destructor must destroy that storage. Copies and destroys must balance out and these operations must not have side effects. Examples of owned types include `std::vector` and `std::string`. The Swift compiler will assume that any types which do not contain pointers are owned types. You can also specify a type is an owned type by using the `import_owned` swift attribute.