[clang] [NFC][analyzer][docs] Document MallocChecker's ownership attributes (PR #121759)

[Kristóf Umann via cfe-commits]

================
@@ -1389,6 +1389,68 @@ Query for this attribute with ``__has_attribute(overloadable)``.
   }];
 }
 
+def OwnershipDocs : Documentation {
+  let Heading = "ownership_holds, ownership_returns, ownership_takes (Clang "
+                "Static Analyzer)";
+  let Category = DocCatFunction;
+  let Content = [{
+
+.. note::
+
+  In order for the Clang Static Analyzer to acknowledge these attributes, the
+  ``Optimistic`` config needs to be set to true for the checker
+  ``unix.DynamicMemoryModeling``:
+
+  ``-Xclang -analyzer-config -Xclang unix.DynamicMemoryModeling:Optimistic=true``
+
+These attributes are used by the Clang Static Analyzer's dynamic memory modeling
+facilities to mark custom allocating/deallocating functions.
+
+All 3 attributes' first parameter of type string is the type of the allocation:
+``malloc``, ``new``, etc. to allow for catching mismatched deallocation bugs to
+be found.
----------------
Szelethus wrote:

Well, from what I understand, you can set the allocation type to something totally custom, like "lasagna" as well, and if you that for all of your custom dynamic memory functions correctly, it should catch mismatch errors (you deallocated memory with "cheese", but it was allocated with "lasagna"). There is a single exception for "malloc" (and should be for new, new[], etc), MallocChecker will be sure that functions with "malloc" annotations will be treated the same as the standard "malloc" and "free".

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