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_nay...@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
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
