[clang] [APINotes] Document immortal reference type annotation (PR #114042)

[Egor Zhdan via cfe-commits]

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

API Notes allow annotating a C++ reference type with its retain/release operations. These are honored by the Swift compiler when the type is used from Swift. Apart from names of C++ functions that need to be called to retain/release the object, API Notes also accept a value of `immortal` which indicates that the object is to be considered alive for the duration of the program.

>From 44863d5d0505d428b006a42c868443fb9d8f1d3a Mon Sep 17 00:00:00 2001
From: Egor Zhdan <e_zhdan at apple.com>
Date: Tue, 29 Oct 2024 12:50:30 +0000
Subject: [PATCH] [APINotes] Document immortal reference type annotation

API Notes allow annotating a C++ reference type with its retain/release operations. These are honored by the Swift compiler when the type is used from Swift. Apart from names of C++ functions that need to be called to retain/release the object, API Notes also accept a value of `immortal` which indicates that the object is to be considered alive for the duration of the program.
---
 clang/docs/APINotes.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst
index dcefa6810dac67..d20c4f9b5ba843 100644
--- a/clang/docs/APINotes.rst
+++ b/clang/docs/APINotes.rst
@@ -169,6 +169,20 @@ declaration kind), all of which are optional:
   to ``SWIFT_RETURNS_INDEPENDENT_VALUE``) or ``computed_property`` (equivalent to
   ``SWIFT_COMPUTED_PROPERTY``).
 
+  ::
+
+    Tags:
+    - Name: OwnedStorage
+      SwiftImportAs: owned
+
+:SwiftRetainOp, SwiftReleaseOp:
+
+  Controls the lifetime operations of a class which uses custom reference
+  counting. The class must be annotated as a reference type using
+  ``SwiftImportAs: reference``. The values are either names of global functions,
+  each taking a single parameter of a pointer type, or ``immortal`` for a type
+  that is considered alive for the duration of the program.
+
   ::
 
     Tags:
@@ -176,6 +190,10 @@ declaration kind), all of which are optional:
       SwiftImportAs: reference
       SwiftReleaseOp: RCRelease
       SwiftRetainOp: RCRetain
+    - Name: ImmortalSingleton
+      SwiftImportAs: reference
+      SwiftReleaseOp: immortal
+      SwiftRetainOp: immortal
 
 :SwiftCopyable: