[clang] 8dc1395 - [clang][docs] document __attribute__((cleanup())) GNU C extension

[Nick Desaulniers via cfe-commits]

Author: Nick Desaulniers
Date: 2023-06-01T11:24:53-07:00
New Revision: 8dc13957cb1752b6a90e299d016e09bb98b0df54

URL: https://github.com/llvm/llvm-project/commit/8dc13957cb1752b6a90e299d016e09bb98b0df54
DIFF: https://github.com/llvm/llvm-project/commit/8dc13957cb1752b6a90e299d016e09bb98b0df54.diff

LOG: [clang][docs] document __attribute__((cleanup())) GNU C extension

Provide an example of how to use this extension and more importantly,
document that cleanup functions are run in reverse nested order.

Reviewed By: erichkeane

Differential Revision: https://reviews.llvm.org/D151732

Added: 
    

Modified: 
    clang/include/clang/Basic/Attr.td
    clang/include/clang/Basic/AttrDocs.td

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index e11439158fc0..3fdd84d2b13b 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -1097,7 +1097,7 @@ def Cleanup : InheritableAttr {
   let Spellings = [GCC<"cleanup">];
   let Args = [DeclArgument<Function, "FunctionDecl">];
   let Subjects = SubjectList<[LocalVar]>;
-  let Documentation = [Undocumented];
+  let Documentation = [CleanupDocs];
 }
 
 def CmseNSEntry : InheritableAttr, TargetSpecificAttr<TargetARM> {

diff  --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index d719f4691251..e3d83234b316 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -7023,3 +7023,30 @@ This attribute may be attached to a function pointer type, where it modifies
 its underlying representation to be a WebAssembly ``funcref``.
   }];
 }
+
+def CleanupDocs : Documentation {
+  let Category = DocCatType;
+  let Content = [{
+This attribute allows a function to be run when a local variable goes out of
+scope. The attribute takes the identifier of a function with a parameter type
+that is a pointer to the type with the attribute.
+
+.. code-block:: c
+
+  static void foo (int *) { ... }
+  static void bar (int *) { ... }
+  void baz (void) {
+    int x __attribute__((cleanup(foo)));
+    {
+      int y __attribute__((cleanup(bar)));
+    }
+  }
+
+The above example will result in a call to ``bar`` being passed the address of
+`y`` when ``y`` goes out of scope, then a call to ``foo`` being passed the
+address of ``x`` when ``x`` goes out of scope. If two or more variables share
+the same scope, their ``cleanup`` callbacks are invoked in the reverse order
+the variables were declared in. It is not possible to check the return value
+(if any) of these ``cleanup`` callback functions.
+}];
+}