r237268 - Made considerable updates to the documentation explaining how to add a new attribute to clang. Cleans up some of the existing wording, as well as adding new information and better explanations.
Aaron Ballman
aaron at aaronballman.com
Wed May 13 11:06:48 PDT 2015
Author: aaronballman
Date: Wed May 13 13:06:48 2015
New Revision: 237268
URL: http://llvm.org/viewvc/llvm-project?rev=237268&view=rev
Log:
Made considerable updates to the documentation explaining how to add a new attribute to clang. Cleans up some of the existing wording, as well as adding new information and better explanations.
Modified:
cfe/trunk/docs/InternalsManual.rst
Modified: cfe/trunk/docs/InternalsManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/InternalsManual.rst?rev=237268&r1=237267&r2=237268&view=diff
==============================================================================
--- cfe/trunk/docs/InternalsManual.rst (original)
+++ cfe/trunk/docs/InternalsManual.rst Wed May 13 13:06:48 2015
@@ -1621,192 +1621,304 @@ How to change Clang
How to add an attribute
-----------------------
+Attributes are a form of metadata that can be attached to a program construct,
+allowing the programmer to pass semantic information along to the compiler for
+various uses. For example, attributes may be used to alter the code generation
+for a program construct, or to provide extra semantic information for static
+analysis. This document explains how to add a custom attribute to Clang.
+Documentation on existing attributes can be found `here
+<//clang.llvm.org/docs/AttributeReference.html>`_.
Attribute Basics
^^^^^^^^^^^^^^^^
-
-Attributes in clang come in two forms: parsed form, and semantic form. Both
-forms are represented via a tablegen definition of the attribute, specified in
-Attr.td.
+Attributes in Clang are handled in three stages: parsing into a parsed attribute
+representation, conversion from a parsed attribute into a semantic attribute,
+and then the semantic handling of the attribute.
+
+Parsing of the attribute is determined by the various syntactic forms attributes
+can take, such as GNU, C++11, and Microsoft style attributes, as well as other
+information provided by the table definition of the attribute. Ultimately, the
+parsed representation of an attribute object is an ``AttributeList`` object.
+These parsed attributes chain together as a list of parsed attributes attached
+to a declarator or declaration specifier. The parsing of attributes is handled
+automatically by Clang, except for attributes spelled as keywords. When
+implementing a keyword attribute, the parsing of the keyword and creation of the
+``AttributeList`` object must be done manually.
+
+Eventually, ``Sema::ProcessDeclAttributeList()`` is called with a ``Decl`` and
+an ``AttributeList``, at which point the parsed attribute can be transformed
+into a semantic attribute. The process by which a parsed attribute is converted
+into a semantic attribute depends on the attribute definition and semantic
+requirements of the attribute. The end result, however, is that the semantic
+attribute object is attached to the ``Decl`` object, and can be obtained by a
+call to ``Decl::getAttr<T>()``.
+
+The structure of the semantic attribute is also governed by the attribute
+definition given in Attr.td. This definition is used to automatically generate
+functionality used for the implementation of the attribute, such as a class
+derived from ``clang::Attr``, information for the parser to use, automated
+semantic checking for some attributes, etc.
``include/clang/Basic/Attr.td``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The first step to adding a new attribute to Clang is to add its definition to
+`include/clang/Basic/Attr.td
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup>`_.
+This tablegen definition must derive from the ``Attr`` (tablegen, not
+semantic) type, or one of its derivatives. Most attributes will derive from the
+``InheritableAttr`` type, which specifies that the attribute can be inherited by
+later redeclarations of the ``Decl`` it is associated with.
+``InheritableParamAttr`` is similar to ``InheritableAttr``, except that the
+attribute is written on a parameter instead of a declaration. If the attribute
+is intended to apply to a type instead of a declaration, such an attribute
+should derive from ``TypeAttr``, and will generally not be given an AST
+representation. (Note that this document does not cover the creation of type
+attributes.) An attribute that inherits from ``IgnoredAttr`` is parsed, but will
+generate an ignored attribute diagnostic when used, which may be useful when an
+attribute is supported by another vendor but not supported by clang.
+
+The definition will specify several key pieces of information, such as the
+semantic name of the attribute, the spellings the attribute supports, the
+arguments the attribute expects, and more. Most members of the ``Attr`` tablegen
+type do not require definitions in the derived definition as the default
+suffice. However, every attribute must specify at least a spelling list, a
+subject list, and a documentation list.
+
+Spellings
+~~~~~~~~~
+All attributes are required to specify a spelling list that denotes the ways in
+which the attribute can be spelled. For instance, a single semantic attribute
+may have a keyword spelling, as well as a C++11 spelling and a GNU spelling. An
+empty spelling list is also permissible and may be useful for attributes which
+are created implicitly. The following spellings are accepted:
+
+ ============ ================================================================
+ Spelling Description
+ ============ ================================================================
+ ``GNU`` Spelled with a GNU-style ``__attribute__((attr))`` syntax and
+ placement.
+ ``CXX11`` Spelled with a C++-style ``[[attr]]`` syntax. If the attribute
+ is meant to be used by Clang, it should set the namespace to
+ ``"clang"``.
+ ``Declspec`` Spelled with a Microsoft-style ``__declspec(attr)`` syntax.
+ ``Keyword`` The attribute is spelled as a keyword, and required custom
+ parsing.
+ ``GCC`` Specifies two spellings: the first is a GNU-style spelling, and
+ the second is a C++-style spelling with the ``gnu`` namespace.
+ Attributes should only specify this spelling for attributes
+ supported by GCC.
+ ``Pragma`` The attribute is spelled as a ``#pragma``, and requires custom
+ processing within the preprocessor. If the attribute is meant to
+ be used by Clang, it should set the namespace to ``"clang"``.
+ Note that this spelling is not used for declaration attributes.
+ ============ ================================================================
+
+Subjects
+~~~~~~~~
+Attributes appertain to one or more ``Decl`` subjects. If the attribute attempts
+to attach to a subject that is not in the subject list, a diagnostic is issued
+automatically. Whether the diagnostic is a warning or an error depends on how
+the attribute's ``SubjectList`` is defined, but the default behavior is to warn.
+The diagnostics displayed to the user are automatically determined based on the
+subjects in the list, but a custom diagnostic parameter can also be specified in
+the ``SubjectList``. The diagnostics generated for subject list violations are
+either ``diag::warn_attribute_wrong_decl_type`` or
+``diag::err_attribute_wrong_decl_type``, and the parameter enumeration is found
+in `include/clang/Sema/AttributeList.h
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/AttributeList.h?view=markup>`_
+If a previously unused Decl node is added to the ``SubjectList``, the logic used
+to automatically determine the diagnostic parameter in `utils/TableGen/ClangAttrEmitter.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_
+may need to be updated.
+
+By default, all subjects in the SubjectList must either be a Decl node defined
+in ``DeclNodes.td``, or a statement node defined in ``StmtNodes.td``. However,
+more complex subjects can be created by creating a ``SubsetSubject`` object.
+Each such object has a base subject which it appertains to (which must be a
+Decl or Stmt node, and not a SubsetSubject node), and some custom code which is
+called when determining whether an attribute appertains to the subject. For
+instance, a ``NonBitField`` SubsetSubject appertains to a ``FieldDecl``, and
+tests whether the given FieldDecl is a bit field. When a SubsetSubject is
+specified in a SubjectList, a custom diagnostic parameter must also be provided.
-First, add your attribute to the `include/clang/Basic/Attr.td
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup>`_
-file.
-
-Each attribute gets a ``def`` inheriting from ``Attr`` or one of its
-subclasses. ``InheritableAttr`` means that the attribute also applies to
-subsequent declarations of the same name. ``InheritableParamAttr`` is similar
-to ``InheritableAttr``, except that the attribute is written on a parameter
-instead of a declaration, type or statement. Attributes inheriting from
-``TypeAttr`` are pure type attributes which generally are not given a
-representation in the AST. Attributes inheriting from ``TargetSpecificAttr``
-are attributes specific to one or more target architectures. An attribute that
-inherits from ``IgnoredAttr`` is parsed, but will generate an ignored attribute
-diagnostic when used. The attribute type may be useful when an attribute is
-supported by another vendor, but not supported by clang.
-
-``Spellings`` lists the strings that can appear in ``__attribute__((here))`` or
-``[[here]]``. All such strings will be synonymous. Possible ``Spellings``
-are: ``GNU`` (for use with GNU-style __attribute__ spellings), ``Declspec``
-(for use with Microsoft Visual Studio-style __declspec spellings), ``CXX11`
-(for use with C++11-style [[foo]] and [[foo::bar]] spellings), and ``Keyword``
-(for use with attributes that are implemented as keywords, like C++11's
-``override`` or ``final``). If you want to allow the ``[[]]`` C++11 syntax, you
-have to define a list of ``Namespaces``, which will let users write
-``[[namespace::spelling]]``. Using the empty string for a namespace will allow
-users to write just the spelling with no "``::``". Attributes which g++-4.8
-or later accepts should also have a ``CXX11<"gnu", "spelling">`` spelling.
-
-``Subjects`` restricts what kinds of AST node to which this attribute can
-appertain (roughly, attach). The subjects are specified via a ``SubjectList``,
-which specify the list of subjects. Additionally, subject-related diagnostics
-can be specified to be warnings or errors, with the default being a warning.
-The diagnostics displayed to the user are automatically determined based on
-the subjects in the list, but a custom diagnostic parameter can also be
-specified in the ``SubjectList``. The diagnostics generated for subject list
-violations are either ``diag::warn_attribute_wrong_decl_type`` or
-``diag::err_attribute_wrong_decl_type``, and the parameter enumeration is
-found in `include/clang/Sema/AttributeList.h
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/AttributeList.h?view=markup>`_
-If you add new Decl nodes to the ``SubjectList``, you may need to update the
-logic used to automatically determine the diagnostic parameter in `utils/TableGen/ClangAttrEmitter.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_.
-
-Diagnostic checking for attribute subject lists is automated except when
+Diagnostic checking for attribute subject lists is automated except when
``HasCustomParsing`` is set to ``1``.
-By default, all subjects in the SubjectList must either be a Decl node defined
-in ``DeclNodes.td``, or a statement node defined in ``StmtNodes.td``. However,
-more complex subjects can be created by creating a ``SubsetSubject`` object.
-Each such object has a base subject which it appertains to (which must be a
-Decl or Stmt node, and not a SubsetSubject node), and some custom code which is
-called when determining whether an attribute appertains to the subject. For
-instance, a ``NonBitField`` SubsetSubject appertains to a ``FieldDecl``, and
-tests whether the given FieldDecl is a bit field. When a SubsetSubject is
-specified in a SubjectList, a custom diagnostic parameter must also be provided.
+Documentation
+~~~~~~~~~~~~~
+All attributes must have some form of documentation associated with them.
+Documentation is table generated on the public web server by a server-side
+process that runs daily. Generally, the documentation for an attribute is a
+stand-alone definition in `include/clang/Basic/AttrDocs.td
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttdDocs.td?view=markup>`_
+that is named after the attribute being documented.
-``Args`` names the arguments the attribute takes, in order. If ``Args`` is
+If the attribute is not for public consumption, or is an implicitly-created
+attribute that has no visible spelling, the documentation list can specify the
+``Undocumented`` object. Otherwise, the attribute should have its documentation
+added to AttrDocs.td.
+
+Documentation derives from the ``Documentation`` tablegen type. All derived
+types must specify a documentation category and the actual documentation itself.
+Additionally, it can specify a custom heading for the attribute, though a
+default heading will be chosen when possible.
+
+There are four predefined documentation categories: ``DocCatFunction`` for
+attributes that appertain to function-like subjects, ``DocCatVariable`` for
+attributes that appertain to variable-like subjects, ``DocCatType`` for type
+attributes, and ``DocCatStmt`` for statement attributes. A custom documentation
+category should be used for groups of attributes with similar functionality.
+Custom categories are good for providing overview information for the attributes
+grouped under it. For instance, the consumed annotation attributes define a
+custom category, ``DocCatConsumed``, that explains what consumed annotations are
+at a high level.
+
+Documentation content (whether it is for an attribute or a category) is written
+using reStructuredText (RST) syntax.
+
+After writing the documentation for the attribute, it should be locally tested
+to ensure that there are no issues generating the documentation on the server.
+Local testing requires a fresh build of clang-tblgen. To generate the attribute
+documentation, execute the following command::
+
+ clang-tblgen -gen-attr-docs -I /path/to/clang/include /path/to/clang/include/clang/Basic/Attr.td -o /path/to/clang/docs/AttributeReference.rst
+
+When testing locally, *do not* commit changes to ``AttributeReference.rst``.
+This file is generated by the server automatically, and any changes made to this
+file will be overwritten.
+
+Arguments
+~~~~~~~~~
+Attributes may optionally specify a list of arguments that can be passed to the
+attribute. Attribute arguments specify both the parsed form and the semantic
+form of the attribute. For example, if ``Args`` is
``[StringArgument<"Arg1">, IntArgument<"Arg2">]`` then
-``__attribute__((myattribute("Hello", 3)))`` will be a valid use. Attribute
-arguments specify both the parsed form and the semantic form of the attribute.
-The previous example shows an attribute which requires two attributes while
-parsing, and the Attr subclass' constructor for the attribute will require a
-string and integer argument.
-
-Diagnostic checking for argument counts is automated except when
-``HasCustomParsing`` is set to ``1``, or when the attribute uses an optional or
-variadic argument. Diagnostic checking for argument semantics is not automated.
-
-If the parsed form of the attribute is more complex, or differs from the
-semantic form, the ``HasCustomParsing`` bit can be set to ``1`` for the class,
-and the parsing code in `Parser::ParseGNUAttributeArgs
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Parse/ParseDecl.cpp?view=markup>`_
-can be updated for the special case. Note that this only applies to arguments
-with a GNU spelling -- attributes with a __declspec spelling currently ignore
+``__attribute__((myattribute("Hello", 3)))`` will be a valid use; it requires
+two arguments while parsing, and the Attr subclass' constructor for the
+semantic attribute will require a string and integer argument.
+
+All arguments have a name and a flag that specifies whether the argument is
+optional. The associated C++ type of the argument is determined by the argument
+definition type. If the existing argument types are insufficient, new types can
+be created, but it requires modifying `utils/TableGen/ClangAttrEmitter.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_
+to properly support the type.
+
+Other Properties
+~~~~~~~~~~~~~~~~
+The ``Attr`` definition has other members which control the behavior of the
+attribute. Many of them are special-purpose and beyond the scope of this
+document, however a few deserve mention.
+
+If the parsed form of the attribute is more complex, or differs from the
+semantic form, the ``HasCustomParsing`` bit can be set to ``1`` for the class,
+and the parsing code in `Parser::ParseGNUAttributeArgs()
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Parse/ParseDecl.cpp?view=markup>`_
+can be updated for the special case. Note that this only applies to arguments
+with a GNU spelling -- attributes with a __declspec spelling currently ignore
this flag and are handled by ``Parser::ParseMicrosoftDeclSpec``.
-Custom accessors can be generated for an attribute based on the spelling list
-for that attribute. For instance, if an attribute has two different spellings:
-'Foo' and 'Bar', accessors can be created:
-``[Accessor<"isFoo", [GNU<"Foo">]>, Accessor<"isBar", [GNU<"Bar">]>]``
-These accessors will be generated on the semantic form of the attribute,
-accepting no arguments and returning a Boolean.
-
-Attributes which do not require an AST node should set the ``ASTNode`` field to
-``0`` to avoid polluting the AST. Note that anything inheriting from
-``TypeAttr`` or ``IgnoredAttr`` automatically do not generate an AST node. All
-other attributes generate an AST node by default. The AST node is the semantic
+Note that setting this member to 1 will opt out of common attribute semantic
+handling, requiring extra implementation efforts to ensure the attribute
+appertains to the appropriate subject, etc.
+
+If the attribute should not be propagated from from a template declaration to an
+instantiation of the template, set the ``Clone`` member to 0. By default, all
+attributes will be cloned to template instantiations.
+
+Attributes that do not require an AST node should set the ``ASTNode`` field to
+``0`` to avoid polluting the AST. Note that anything inheriting from
+``TypeAttr`` or ``IgnoredAttr`` automatically do not generate an AST node. All
+other attributes generate an AST node by default. The AST node is the semantic
representation of the attribute.
-Attributes which do not require custom semantic handling should set the
-``SemaHandler`` field to ``0``. Note that anything inheriting from
-``IgnoredAttr`` automatically do not get a semantic handler. All other
-attributes are assumed to use a semantic handler by default. Attributes
-without a semantic handler are not given a parsed attribute Kind enumeration.
-
-The ``LangOpts`` field can be used to specify a list of language options
-required by the attribute. For instance, all of the CUDA-specific attributes
-specify ``[CUDA]`` for the ``LangOpts`` field, and when the CUDA language
-option is not enabled, an "attribute ignored" warning diagnostic is emitted.
-Since language options are not table generated nodes, new language options must
-be created manually and should specify the spelling used by ``LangOptions`` class.
-
-Target-specific attribute sometimes share a spelling with other attributes in
-different targets. For instance, the ARM and MSP430 targets both have an
-attribute spelled ``GNU<"interrupt">``, but with different parsing and semantic
-requirements. To support this feature, an attribute inheriting from
-``TargetSpecificAttribute`` make specify a ``ParseKind`` field. This field
-should be the same value between all arguments sharing a spelling, and
-corresponds to the parsed attribute's Kind enumeration. This allows attributes
-to share a parsed attribute kind, but have distinct semantic attribute classes.
-For instance, ``AttributeList::AT_Interrupt`` is the shared parsed attribute
-kind, but ARMInterruptAttr and MSP430InterruptAttr are the semantic attributes
-generated.
-
-By default, when declarations are merging attributes, an attribute will not be
-duplicated. However, if an attribute can be duplicated during this merging
-stage, set ``DuplicatesAllowedWhileMerging`` to ``1``, and the attribute will
+The ``LangOpts`` field specifies a list of language options required by the
+attribute. For instance, all of the CUDA-specific attributes specify ``[CUDA]``
+for the ``LangOpts`` field, and when the CUDA language option is not enabled, an
+"attribute ignored" warning diagnostic is emitted. Since language options are
+not table generated nodes, new language options must be created manually and
+should specify the spelling used by ``LangOptions`` class.
+
+Custom accessors can be generated for an attribute based on the spelling list
+for that attribute. For instance, if an attribute has two different spellings:
+'Foo' and 'Bar', accessors can be created:
+``[Accessor<"isFoo", [GNU<"Foo">]>, Accessor<"isBar", [GNU<"Bar">]>]``
+These accessors will be generated on the semantic form of the attribute,
+accepting no arguments and returning a ``bool``.
+
+Attributes that do not require custom semantic handling should set the
+``SemaHandler`` field to ``0``. Note that anything inheriting from
+``IgnoredAttr`` automatically do not get a semantic handler. All other
+attributes are assumed to use a semantic handler by default. Attributes
+without a semantic handler are not given a parsed attribute ``Kind`` enumerator.
+
+Target-specific attributes may share a spelling with other attributes in
+different targets. For instance, the ARM and MSP430 targets both have an
+attribute spelled ``GNU<"interrupt">``, but with different parsing and semantic
+requirements. To support this feature, an attribute inheriting from
+``TargetSpecificAttribute`` may specify a ``ParseKind`` field. This field
+should be the same value between all arguments sharing a spelling, and
+corresponds to the parsed attribute's ``Kind`` enumerator. This allows
+attributes to share a parsed attribute kind, but have distinct semantic
+attribute classes. For instance, ``AttributeList::AT_Interrupt`` is the shared
+parsed attribute kind, but ARMInterruptAttr and MSP430InterruptAttr are the
+semantic attributes generated.
+
+By default, when declarations are merging attributes, an attribute will not be
+duplicated. However, if an attribute can be duplicated during this merging
+stage, set ``DuplicatesAllowedWhileMerging`` to ``1``, and the attribute will
be merged.
-By default, attribute arguments are parsed in an evaluated context. If the
-arguments for an attribute should be parsed in an unevaluated context (akin to
-the way the argument to a ``sizeof`` expression is parsed), you can set
+By default, attribute arguments are parsed in an evaluated context. If the
+arguments for an attribute should be parsed in an unevaluated context (akin to
+the way the argument to a ``sizeof`` expression is parsed), set
``ParseArgumentsAsUnevaluated`` to ``1``.
-If additional functionality is desired for the semantic form of the attribute,
-the ``AdditionalMembers`` field specifies code to be copied verbatim into the
-semantic attribute class object.
-
-All attributes must have one or more form of documentation, which is provided
-in the ``Documentation`` list. Generally, the documentation for an attribute
-is a stand-alone definition in `include/clang/Basic/AttrDocs.td
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttdDocs.td?view=markup>`_
-that is named after the attribute being documented. Each documentation element
-is given a ``Category`` (variable, function, or type) and ``Content``. A single
-attribute may contain multiple documentation elements for distinct categories.
-For instance, an attribute which can appertain to both function and types (such
-as a calling convention attribute), should contain two documentation elements.
-The ``Content`` for an attribute uses reStructuredText (RST) syntax.
-
-If an attribute is used internally by the compiler, but is not written by users
-(such as attributes with an empty spelling list), it can use the
-``Undocumented`` documentation element.
+If additional functionality is desired for the semantic form of the attribute,
+the ``AdditionalMembers`` field specifies code to be copied verbatim into the
+semantic attribute class object, with ``public`` access.
Boilerplate
^^^^^^^^^^^
-
All semantic processing of declaration attributes happens in `lib/Sema/SemaDeclAttr.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup>`_,
-and generally starts in the ``ProcessDeclAttribute`` function. If your
-attribute is a "simple" attribute -- meaning that it requires no custom
-semantic processing aside from what is automatically provided for you, you can
-add a call to ``handleSimpleAttribute<YourAttr>(S, D, Attr);`` to the switch
-statement. Otherwise, write a new ``handleYourAttr()`` function, and add that
-to the switch statement.
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup>`_,
+and generally starts in the ``ProcessDeclAttribute()`` function. If the
+attribute is a "simple" attribute -- meaning that it requires no custom semantic
+processing aside from what is automatically provided, add a call to
+``handleSimpleAttribute<YourAttr>(S, D, Attr);`` to the switch statement.
+Otherwise, write a new ``handleYourAttr()`` function, and add that to the switch
+statement. Please do not implement handling logic directly in the ``case`` for
+the attribute.
+
+Unless otherwise specified by the attribute definition, common semantic checking
+of the parsed attribute is handled automatically. This includes diagnosing
+parsed attributes that do not appertain to the given ``Decl``, ensuring the
+correct minimum number of arguments are passed, etc.
-If your attribute causes extra warnings to fire, define a ``DiagGroup`` in
+If the attribute adds additional warnings, define a ``DiagGroup`` in
`include/clang/Basic/DiagnosticGroups.td
<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticGroups.td?view=markup>`_
-named after the attribute's ``Spelling`` with "_"s replaced by "-"s. If you're
-only defining one diagnostic, you can skip ``DiagnosticGroups.td`` and use
-``InGroup<DiagGroup<"your-attribute">>`` directly in `DiagnosticSemaKinds.td
+named after the attribute's ``Spelling`` with "_"s replaced by "-"s. If there
+is only a single diagnostic, it is permissible to use ``InGroup<DiagGroup<"your-attribute">>``
+directly in `DiagnosticSemaKinds.td
<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticSemaKinds.td?view=markup>`_
All semantic diagnostics generated for your attribute, including automatically-
-generated ones (such as subjects and argument counts), should have a
+generated ones (such as subjects and argument counts), should have a
corresponding test case.
-The meat of your attribute
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Find an appropriate place in Clang to do whatever your attribute needs to do.
-Check for the attribute's presence using ``Decl::getAttr<YourAttr>()``.
-
-Update the :doc:`LanguageExtensions` document to describe your new attribute.
+Semantic handling
+^^^^^^^^^^^^^^^^^
+Most attributes are implemented to have some effect on the compiler. For
+instance, to modify the way code is generated, or to add extra semantic checks
+for an analysis pass, etc. Having added the attribute definition and conversion
+to the semantic representation for the attribute, what remains is to implement
+the custom logic requiring use of the attribute.
+
+The ``clang::Decl`` object can be queried for the presence or absence of an
+attribute using ``hasAttr<T>()``. To obtain a pointer to the semantic
+representation of the attribute, ``getAttr<T>`` may be used.
How to add an expression or statement
-------------------------------------
More information about the cfe-commits
mailing list