Index: include/clang/Basic/Attr.td =================================================================== --- include/clang/Basic/Attr.td (revision 293612) +++ include/clang/Basic/Attr.td (working copy) @@ -462,9 +462,10 @@ } def Annotate : InheritableParamAttr { - let Spellings = [GNU<"annotate">]; + let Spellings = [GNU<"annotate">, + CXX11<"", "annotate", 201612>]; let Args = [StringArgument<"Annotation">]; - let Documentation = [Undocumented]; + let Documentation = [AnnotateDocs]; } def ARMInterrupt : InheritableAttr, TargetSpecificAttr { Index: lib/Sema/SemaStmtAttr.cpp =================================================================== --- lib/Sema/SemaStmtAttr.cpp (revision 293612) +++ lib/Sema/SemaStmtAttr.cpp (working copy) @@ -23,6 +23,24 @@ using namespace clang; using namespace sema; +static Attr *handleAnnotateAttr(Sema &S, Stmt *St, const AttributeList &A, + SourceRange Range) { + // Assert string literal as the annotation's argument. + StringRef Str; + if (!S.checkStringLiteralArgumentAttr(A, 0, Str)) + return nullptr; + + // Assert single argument + if (A.getNumArgs() > 1) { + S.Diag(A.getLoc(), diag::err_attribute_wrong_number_arguments) + << A.getName() << 1; + return nullptr; + } + + return ::new (S.Context) AnnotateAttr(A.getRange(), S.Context, Str, + A.getAttributeSpellingListIndex()); +} + static Attr *handleFallThroughAttr(Sema &S, Stmt *St, const AttributeList &A, SourceRange Range) { FallThroughAttr Attr(A.getRange(), S.Context, @@ -273,6 +291,8 @@ diag::warn_unhandled_ms_attribute_ignored : diag::warn_unknown_attribute_ignored) << A.getName(); return nullptr; + case AttributeList::AT_Annotate: + return handleAnnotateAttr(S, St, A, Range); case AttributeList::AT_FallThrough: return handleFallThroughAttr(S, St, A, Range); case AttributeList::AT_LoopHint: Index: test/SemaCXX/attr-annotate.cpp =================================================================== --- test/SemaCXX/attr-annotate.cpp (nonexistent) +++ test/SemaCXX/attr-annotate.cpp (working copy) @@ -0,0 +1,17 @@ +// RUN: %clang_cc1 -std=c++11 -fsyntax-only -verify %s + +[[annotate("foo")]] void foo() { + // C++11 decl annotations + [[annotate("bar")]] int x; + [[annotate(1)]] int y; // expected-error {{'annotate' attribute requires a string}} + [[annotate("bar", 1)]] int z1; // expected-error {{'annotate' attribute takes one argument}} + [[annotate()]] int z2; // expected-error {{'annotate' attribute takes one argument}} + [[annotate]] int z3; // expected-error {{'annotate' attribute takes one argument}} + + // C++11 NullStmt annotations + [[annotate("bar")]]; + [[annotate(1)]]; // expected-error {{'annotate' attribute requires a string}} + [[annotate("bar", 1)]]; // expected-error {{'annotate' attribute takes one argument}} + [[annotate()]]; // expected-error {{'annotate' attribute takes one argument}} + [[annotate]]; // expected-error {{'annotate' attribute takes one argument}} +} Index: include/clang/Basic/AttrDocs.td =================================================================== --- include/clang/Basic/AttrDocs.td (revision 293612) +++ include/clang/Basic/AttrDocs.td (working copy) @@ -2812,3 +2812,97 @@ ensure that this class cannot be subclassed. }]; } + +def DocCatGeneric : DocumentationCategory<"Generic Attributes"> { + let Content = [{ +These attributes are suitable for passing arbitrary information from the code to +a plugin or other clang based tools such as source code transformers, generators, +collectors and similar. The attributes are not tied to any type of solution or +predefined functionality and may be used in a variety of situations when a generic +attribute suffice. + }]; +} + +def AnnotateDocs : Documentation { + let Category = DocCatGeneric; + let Content = [{ +The ``annotate`` attribute may be used to annotate any type of declarations or +statements with arbitrary information that are propagated to the AST. The attribute +takes one string parameter containing the annotation value. The content, format +and the exact meaning of the value is up to the programmer to decide. + +C++11 spelling examples: + +.. code-block:: c++ + + class [[annotate("plain")]] Object + { . . . }; + + int main(int argc, char* argv[]) + { + [[annotate("local_var")]] // Decl annotation + int n = 1 ; + + // Multiple Stmt annotations + [[annotate("group-A"), annotate("opt-1:2")]] + switch(n) + { . . . } + return 0; + } + +Looking at the AST for the example above reveals that any annotated statements +are wrapped into an AttributedStmt node together with the annotation attributes +in comparison to annotated declarations where the annotation attributes are +attached directly beneath the declaration node. + +.. code-block:: text + + TranslationUnitDecl 0x345fb20 <> + | . . . + |-CXXRecordDecl 0x34b9b58 line:2:29 class Object definition + | |-AnnotateAttr 0x34b9c10 "plain" + | |-CXXRecordDecl 0x34b9cb8 col:29 implicit class Object + | |-AccessSpecDecl 0x34b9d50 col:3 public + | ` . . . + `-FunctionDecl 0x34ba240 line:12:5 main 'int (int, char **)' + |-ParmVarDecl 0x34ba020 col:14 argc 'int' + |-ParmVarDecl 0x34ba130 col:26 argv 'char **':'char **' + `-CompoundStmt 0x34ba7f0 + |-DeclStmt 0x34ba4d0 + | `-VarDecl 0x34ba400 col:6 used n 'int' cinit + | |-IntegerLiteral 0x34ba4b0 'int' 1 + | `-AnnotateAttr 0x34ba460 "local_var" + |-AttributedStmt 0x34ba790 + | |-AnnotateAttr 0x34ba750 "opt-1:2" + | |-AnnotateAttr 0x34ba770 "group-A" + | `-SwitchStmt 0x34ba608 + | . . . + `-ReturnStmt 0x34ba7d8 + `-IntegerLiteral 0x34ba7b8 'int' 0 + +The GNU spelling, ``__attribute((annotate("str")))``, is limited to annotating +declarations but is at the same time a bit more relaxed on the allowed insertion +points compared to the C++11 spelling that needs to be defined prior to any +declaration or statement. + +In the example below the GNU-only insertion points are shown as __attr. + +.. code-block:: c++ + + void __attr function/method(int __attr n) __attr + int __attr n = 1; + +(Note that it is also possible to annotate arbitrary expressions using the GCC +syntax ``int __builtin_annotation(int, "str")`` where the ``int`` is an integer +of any compiler supported bit-width and with the return value set to the same +as the parameter value. However, the annotation does not show up in the AST as +an AnnotateAttr but as an ordinary CallExpr). + +The annotations of variable, function and method declarations (and expressions) +are forwarded into IR during code generation using the LLVM annotation intrinsic +functions or by adding the information to a global annotation table. The +information added, in either case, are the annotation string, file name and +line number of the declaration or expression. These IR annotations may be used +by optimizers or other back-end tools. + }]; +}