[clang] [APINotes] Document `SwiftReturnOwnership` annotation (PR #182541)

[Egor Zhdan via cfe-commits]

https://github.com/egorzhdan created https://github.com/llvm/llvm-project/pull/182541

The API Notes attribute was added in `48f7f63a`, but wasn't documented.

>From 8f5e5a2502c7777d9b074bbcce32165e18531281 Mon Sep 17 00:00:00 2001
From: Egor Zhdan <e_zhdan at apple.com>
Date: Fri, 20 Feb 2026 17:06:17 +0000
Subject: [PATCH] [APINotes] Document `SwiftReturnOwnership` annotation

The API Notes attribute was added in `48f7f63a`, but wasn't documented.
---
 clang/docs/APINotes.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst
index e142cfa62e5a2..0018e4c883542 100644
--- a/clang/docs/APINotes.rst
+++ b/clang/docs/APINotes.rst
@@ -438,6 +438,31 @@ declaration kind), all of which are optional:
     - Name: NSIndexSet
       SwiftBridge: IndexSet
 
+:SwiftReturnOwnership:
+
+  Used for methods and functions. Specifies the ownership convention for the
+  return value when it is a foreign reference type (a type imported as
+  ``SwiftImportAs: reference``). Possible values are:
+
+  - ``retained`` --- the caller receives an owned reference
+    (equivalent to ``__attribute__((swift_attr("returns_retained")))``).
+  - ``unretained`` --- the caller receives an unowned reference
+    (equivalent to ``__attribute__((swift_attr("returns_unretained")))``).
+
+  ::
+
+    Functions:
+    - Name: createRefCounted
+      SwiftReturnOwnership: retained
+    - Name: getSharedRefCounted
+      SwiftReturnOwnership: unretained
+    Tags:
+    - Name: ImmortalRefType
+      SwiftImportAs: reference
+      Methods:
+      - Name: createChild
+        SwiftReturnOwnership: retained
+
 :DesignatedInit:
 
   Used for init methods. Equivalent to ``NS_DESIGNATED_INITIALIZER``.