[clang] [clang][docs] Improve documentation of [[ownership_returns]] attribute (PR #191005)

[Balázs Benics via cfe-commits]

https://github.com/steakhal updated https://github.com/llvm/llvm-project/pull/191005

>From 07dc9e9666cd3bbf78401c751509adfbff2ceac8 Mon Sep 17 00:00:00 2001
From: Balazs Benics <benicsbalazs at gmail.com>
Date: Wed, 8 Apr 2026 17:17:23 +0100
Subject: [PATCH 1/3] [clang][docs] Improve documentation of
 [[ownership_returns]] attribute

The 2 parameter use of this attribute wasn't documented.
---
 clang/docs/analyzer/user-docs/Annotations.rst | 11 ++++++++++-
 clang/include/clang/Basic/AttrDocs.td         | 14 ++++++++++++--
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst
index 11f15939ecfaf..5439aeba2c1d4 100644
--- a/clang/docs/analyzer/user-docs/Annotations.rst
+++ b/clang/docs/analyzer/user-docs/Annotations.rst
@@ -174,12 +174,21 @@ If a project uses custom functions for dynamic memory management (that e.g. act
 Attribute 'ownership_returns' (Clang-specific)
 ----------------------------------------------
 
-Use this attribute to mark functions that return dynamically allocated memory. Takes a single argument, the type of the allocation (e.g. ``malloc`` or ``new``).
+Use this attribute to mark functions that return dynamically allocated memory.
+The first argument is the type of the allocation (e.g. ``malloc``, ``new``, or any other identifier).
+An optional second argument is the 1-based index of the function parameter that specifies the allocation size in bytes.
+The referenced parameter must have an integral type.
+
+This attribute may appear at most once per function declaration.
 
 .. code-block:: c
 
+  // Without size parameter:
   void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
 
+  // With size parameter (parameter 1 is the allocation size in bytes):
+  void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz);
+
 Attribute 'ownership_takes' (Clang-specific)
 --------------------------------------------
 
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 2ffbecfc2366b..3e6db7ca99eb2 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -1639,8 +1639,15 @@ the Clang Static Analyzer makes sure that allocating functions annotated with
 ``malloc`` are treated like they used the standard ``malloc()``, and can be
 safely deallocated with the standard ``free()``.
 
-* Use ``ownership_returns`` to mark a function as an allocating function. Takes
-  1 parameter to denote the allocation type.
+* Use ``ownership_returns`` to mark a function as an allocating function.
+  It takes 1 or 2 parameters.
+  The first parameter is a user-provided identifier representing the "kind" of the allocation.
+  This is basically what is enforced when checking the deallocation.
+  The second parameter is optional.
+  It represents the index of the parameter that represents the allocation size in bytes (counting from 1).
+  The referenced parameter must have some integral type.
+  This attribute may appear at most once per declaration;
+  If forward declarations have this attribute, those must have the same parameters.
 * Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2
   parameters: the allocation type, and the index of the parameter that is being
   deallocated (counting from 1).
@@ -1662,6 +1669,9 @@ Example:
   // memory using malloc().
   void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
 
+  // 'sz' (parameter 1) is the allocation size.
+  void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz);
+
   // Denotes that my_free will deallocate its parameter using free().
   void __attribute((ownership_takes(malloc, 1))) my_free(void *);
 

>From 753270be8cf90672af4e9b3256aa16153c66bed5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20Benics?= <benicsbalazs at gmail.com>
Date: Wed, 8 Apr 2026 17:59:03 +0100
Subject: [PATCH 2/3] Add param name in example

---
 clang/docs/analyzer/user-docs/Annotations.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst
index 5439aeba2c1d4..47abbe48bc7ab 100644
--- a/clang/docs/analyzer/user-docs/Annotations.rst
+++ b/clang/docs/analyzer/user-docs/Annotations.rst
@@ -184,7 +184,7 @@ This attribute may appear at most once per function declaration.
 .. code-block:: c
 
   // Without size parameter:
-  void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
+  void __attribute((ownership_returns(malloc))) *my_malloc(size_t sz);
 
   // With size parameter (parameter 1 is the allocation size in bytes):
   void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz);

>From bb6cf3944938e5638f92c1570a6c8aa1ac0c91f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20Benics?= <benicsbalazs at gmail.com>
Date: Wed, 8 Apr 2026 18:00:06 +0100
Subject: [PATCH 3/3] Use full-stop instead of semicolon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Donát Nagy <donat.nagy at ericsson.com>
---
 clang/include/clang/Basic/AttrDocs.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 3e6db7ca99eb2..65db3e59fb24d 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -1646,7 +1646,7 @@ safely deallocated with the standard ``free()``.
   The second parameter is optional.
   It represents the index of the parameter that represents the allocation size in bytes (counting from 1).
   The referenced parameter must have some integral type.
-  This attribute may appear at most once per declaration;
+  This attribute may appear at most once per declaration.
   If forward declarations have this attribute, those must have the same parameters.
 * Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2
   parameters: the allocation type, and the index of the parameter that is being