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

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Balázs Benics (steakhal)

<details>
<summary>Changes</summary>

The 2 parameter use of this attribute wasn't documented.

This clarification is based of the following two commits:
 - https://github.com/llvm/llvm-project/commit/d21139a34f51
 - https://github.com/llvm/llvm-project/commit/893a303962608

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


2 Files Affected:

- (modified) clang/docs/analyzer/user-docs/Annotations.rst (+10-1) 
- (modified) clang/include/clang/Basic/AttrDocs.td (+12-2) 


``````````diff
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 *);
 

``````````

</details>


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