[clang] 8441363 - Document the [[clang::annotate]] attribute (#203303)

[via cfe-commits]

Author: Aaron Ballman
Date: 2026-06-23T08:09:57-04:00
New Revision: 844136348ef4c03e84bed0a51d8557d53f466b0d

URL: https://github.com/llvm/llvm-project/commit/844136348ef4c03e84bed0a51d8557d53f466b0d
DIFF: https://github.com/llvm/llvm-project/commit/844136348ef4c03e84bed0a51d8557d53f466b0d.diff

LOG: Document the [[clang::annotate]] attribute (#203303)

The new documentation mirrors the existing docs for annotate_type.

Added: 
    

Modified: 
    clang/include/clang/Basic/Attr.td
    clang/include/clang/Basic/AttrDocs.td
    clang/test/AST/undocumented-attrs.cpp

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index a222092cd42cf..12bc0732fc19e 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -1039,7 +1039,7 @@ def Annotate : InheritableParamOrStmtAttr {
   }];
   let PragmaAttributeSupport = 1;
   let AcceptsExprPack = 1;
-  let Documentation = [Undocumented];
+  let Documentation = [AnnotateDocs];
 }
 
 def AnnotateType : TypeAttr {

diff  --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 04362de2d5be2..0f1a66ec34197 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -9172,6 +9172,33 @@ point."
 }];
 }
 
+def AnnotateDocs : Documentation {
+  let Category = DocCatDecl;
+  let Content = [{
+The `annotate` attribute is used to add annotations to declarations or statements,
+typically for use by static analysis tools that are not integrated into the
+core Clang compiler (e.g., Clang-Tidy checks or out-of-tree Clang-based tools).
+It is a counterpart to the `annotate_type` attribute, which serves the same
+purpose, but for types.
+
+The attribute takes a mandatory string literal argument specifying the
+annotation category and an arbitrary number of optional arguments that provide
+additional information specific to the annotation category. The optional
+arguments must be constant expressions of arbitrary type.
+
+For example:
+
+.. code-block:: c++
+
+  [[clang::annotate("category1", "foo", 1)]] void func(int val [[clang::annotate("category2")]]) {
+    [[clang::annotate("category3")]] if (val) {
+
+    }
+  }
+
+  }];
+}
+
 def AnnotateTypeDocs : Documentation {
   let Category = DocCatType;
   let Heading = "annotate_type";

diff  --git a/clang/test/AST/undocumented-attrs.cpp b/clang/test/AST/undocumented-attrs.cpp
index eeebd7f938644..7f02fdb3622d6 100644
--- a/clang/test/AST/undocumented-attrs.cpp
+++ b/clang/test/AST/undocumented-attrs.cpp
@@ -11,7 +11,6 @@ CHECK-NEXT:	AcquiredBefore
 CHECK-NEXT:	Alias
 CHECK-NEXT:	Aligned
 CHECK-NEXT:	AnalyzerNoReturn
-CHECK-NEXT:	Annotate
 CHECK-NEXT:	ArcWeakrefUnavailable
 CHECK-NEXT:	AvailableOnlyInDefaultEvalMethod
 CHECK-NEXT:	Blocks