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

[Donát Nagy via cfe-commits]

================
@@ -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;
----------------
NagyDonat wrote:

```suggestion
  This attribute may appear at most once per declaration.
```
Or start the next line with a lowercase letter.

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