[NFC][analyzer][docs] Improve Annotations.rst

[NagyDonat]

This commit fixes three issues within the documentation file Annotations.rst which was recently created by my earlier commit #122246 .

(1) The section title "Annotations to Enhance Generic Checks" is changed to "General Purpose Annotations" because it was a bit too verbose and it used the obsolete name "checks" for what we now call "checkers" in the static analyzer.

(2) Several code blocks were missing from the generated html because I accidentally used .. code-block: c instead of .. code-block:: c and so Sphinx parsed them as comment blocks. (Without printing any error or warning...)

(3) The ownership_* attributes (which are used by MallocChecker) were missing from this document, so I wrote a section that briefly describes them and links to their full documentation.

[llvmbot]

@llvm/pr-subscribers-clang-static-analyzer-1

@llvm/pr-subscribers-clang

Author: Donát Nagy (NagyDonat)

Changes

This commit fixes three issues within the documentation file Annotations.rst which was recently created by my earlier commit #122246 .

(1) The section title "Annotations to Enhance Generic Checks" is changed to "General Purpose Annotations" because it was a bit too verbose and it used the obsolete name "checks" for what we now call "checkers" in the static analyzer.

(2) Several code blocks were missing from the generated html because I accidentally used .. code-block: c instead of .. code-block:: c and so Sphinx parsed them as comment blocks. (Without printing any error or warning...)

(3) The ownership_* attributes (which are used by MallocChecker) were missing from this document, so I wrote a section that briefly describes them and links to their full documentation.

---

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

1 Files Affected:

• (modified) clang/docs/analyzer/user-docs/Annotations.rst (+43-8)

diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst
index d87e8f4df99c31..2ed609d3594c4f 100644
--- a/clang/docs/analyzer/user-docs/Annotations.rst
+++ b/clang/docs/analyzer/user-docs/Annotations.rst
@@ -23,8 +23,8 @@ recognized by GCC. Their use can be conditioned using preprocessor macros
 .. contents::
    :local:
 
-Annotations to Enhance Generic Checks
-_____________________________________
+General Purpose Annotations
+___________________________
 
 Null Pointer Checking
 #####################
@@ -79,7 +79,7 @@ implemented with a macro, with the macro performing a check for the assertion
 condition and, when the check fails, calling an assertion handler.  For
 example, consider the following code fragment:
 
-.. code-block: c
+.. code-block:: c
 
   void foo(int *p) {
     assert(p != NULL);
@@ -87,7 +87,7 @@ example, consider the following code fragment:
 
 When this code is preprocessed on Mac OS X it expands to the following:
 
-.. code-block: c
+.. code-block:: c
 
   void foo(int *p) {
     (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0);
@@ -131,7 +131,7 @@ return.
 On Mac OS X, the function prototype for ``__assert_rtn`` (declared in
 ``assert.h``) is specifically annotated with the 'noreturn' attribute:
 
-.. code-block: c
+.. code-block:: c
 
   void __assert_rtn(const char *, const char *, int, const char *) __attribute__((__noreturn__));
 
@@ -151,7 +151,7 @@ the use of preprocessor macros.
 
 **Example**
 
-.. code-block: c
+.. code-block:: c
 
   #ifndef CLANG_ANALYZER_NORETURN
   #if __has_feature(attribute_analyzer_noreturn)
@@ -163,6 +163,42 @@ the use of preprocessor macros.
 
   void my_assert_rtn(const char *, const char *, int, const char *) CLANG_ANALYZER_NORETURN;
 
+Dynamic Memory Modeling Annotations
+###################################
+
+If a project uses custom functions for dynamic memory management (that e.g. act as wrappers around ``malloc``/``free`` or ``new``/``delete`` in C++) and the analyzer cannot "see" the _definitions_ of these functions, it's possible to annotate their declarations to let the analyzer model their behavior. (Otherwise the analyzer cannot know that the opaque ``my_free()`` is basically equivalent to a standard ``free()`` call.)
+
+**This page only provides a brief list of these annotations.** For a full documentation, see the main `Attributes in Clang <../../AttributeReference.html#ownership-holds-ownership-returns-ownership-takes-clang-static-analyzer>`_ page.
+
+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``).
+
+.. code-block:: c
+
+  void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
+
+Attribute 'ownership_takes' (Clang-specific)
+--------------------------------------------
+
+Use this attribute to mark functions that deallocate memory. Takes two arguments: the type of the allocation (e.g. ``malloc`` or ``new``) and the index of the parameter that is being deallocated (counting from 1).
+
+.. code-block:: c
+
+  void __attribute((ownership_takes(malloc, 1))) my_free(void *);
+
+Attribute 'ownership_holds' (Clang-specific)
+--------------------------------------------
+
+Use this attribute to mark functions that take ownership of memory and will deallocate it at some unspecified point in the future. Takes two arguments: the type of the allocation (e.g. ``malloc`` or ``new``) and the index of the parameter that is being held (counting from 1).
+
+.. code-block:: c
+
+  void __attribute((ownership_holds(malloc, 2))) store_in_table(int key, record_t *val);
+
+The annotations ``ownership_takes`` and ``ownership_holds`` both prevent memory leak reports (concerning the specified argument); the difference between them is that using taken memory is a use-after-free error, while using held memory is assumed to be legitimate.
+
 Mac OS X API Annotations
 ________________________
 
@@ -207,7 +243,7 @@ functions allows the analyzer to perform extra checking.
 
 **Example**
 
-.. code-block: objc
+.. code-block:: objc
 
   #import <Foundation/Foundation.h>;
 
@@ -597,7 +633,6 @@ returned object.
     LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter();
   }
 
-
   // Note that the annotation only has to be applied to the function declaration.
   OSObject * MyClass::myFieldGetter() {
     return f;