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

[nickdesaulniers]

Summary

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

[erichkeane]

clang/include/clang/Basic/AttrDocs.td

7045

[nickdesaulniers]

• fixup last sentence as per @erichkeane

[erichkeane]

Still LGTM!

[nickdesaulniers]

• add note about function signature

[nickdesaulniers]

• add note about reverse declaration order for variables declared in the same scope

[nickdesaulniers]

• rebase

clang/include/clang/Basic/Attr.td

def OSConsumesThis : InheritableAttr {
   let Documentation = [RetainBehaviorDocs];
   let SimpleHandler = 1;
 }
 
 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> {
   let Spellings = [GNU<"cmse_nonsecure_entry">];
   let Subjects = SubjectList<[Function]>;
   let LangOpts = [Cmse];
   let Documentation = [ArmCmseNSEntryDocs];
 }

clang/include/clang/Basic/AttrDocs.td

 def WebAssemblyFuncrefDocs : Documentation {
   let Category = DocCatType;
   let Content = [{
 Clang supports the ``__funcref`` attribute for the WebAssembly target. 
 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.
+}];
+}