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

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: None (fahadnayyar)

<details>
<summary>Changes</summary>

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`.

---
Full diff: https://github.com/llvm/llvm-project/pull/143545.diff


1 Files Affected:

- (modified) clang/docs/APINotes.rst (+46) 


``````````diff
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

``````````

</details>


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