[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)

[via cfe-commits]

https://github.com/fahadnayyar created https://github.com/llvm/llvm-project/pull/143545

Added documentation about the usage of `SwiftReturnOwnership:` to annotate C/C++ and ObjC/C++ APIs returning C++ `SWIFT_SHARED_REFERENCE` types with `SWIFT_RETURNS_(UN)RETAINED`.

>From b4bfb1e4105b5d872aee390d0a1745e3c657dd00 Mon Sep 17 00:00:00 2001
From: Fahad Nayyar <f_nayyar at apple.com>
Date: Tue, 10 Jun 2025 07:51:51 -0700
Subject: [PATCH] [NFC] [API Notes] [Documentation] Add documentation for
 SwiftReturnOwnership

---
 clang/docs/APINotes.rst | 46 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst
index d20c4f9b5ba84..3b8b463ed6af7 100644
--- a/clang/docs/APINotes.rst
+++ b/clang/docs/APINotes.rst
@@ -195,6 +195,52 @@ declaration kind), all of which are optional:
       SwiftReleaseOp: immortal
       SwiftRetainOp: immortal
 
+:SwiftReturnOwnership:
+
+  Specifies the ownership convention of a function or method returning a C++ type
+  that has been imported as a Swift reference type using ``SwiftImportAs: reference``.
+  This allows Swift to correctly manage the retain and release operations at the
+  language boundary.
+
+  The possible values are:
+
+  - ``retained`` — Indicates that the function or method returns a +1 reference.
+    Swift will take ownership and is responsible for releasing it.
+    Equivalent to ``SWIFT_RETURNS_RETAINED``.
+  - ``unretained`` — Indicates that the function or method returns a +0 reference.
+    The caller must ensure the returned object remains alive.
+    Equivalent to ``SWIFT_RETURNS_UNRETAINED``.
+
+  This attribute can be applied to:
+
+  - **C++ functions**
+  - **C++ instance or static methods**
+  - **Objective-C / Objective-C++ methods or functions that return a C++ reference type**
+
+  When omitted, the default behavior is that Swift assumes the function returns an
+  ```unretained``` (```+0```) reference unless the function or API has ``create`` or ``copy`` string in their name. 
+  Use ``SwiftReturnOwnership`` to override this and
+  ensure proper memory management when interoperating with Swift's ARC.
+
+  ::
+
+    Tags:
+    - Name: ImmortalRefType
+      SwiftImportAs: reference
+      Methods:
+        - Name: methodReturningFrt__
+        - Name: methodReturningFrt_returns_unretained
+          SwiftReturnOwnership: unretained
+        - Name: methodReturningFrt_returns_retained
+          SwiftReturnOwnership: retained
+
+    Functions:
+      - Name: functionReturningFrt__
+      - Name: functionReturningFrt_returns_unretained
+        SwiftReturnOwnership: unretained
+      - Name: functionReturningFrt_returns_retained
+        SwiftReturnOwnership: retained
+
 :SwiftCopyable:
 
   Allows annotating a C++ class as non-copyable in Swift. Equivalent to