diff options
Diffstat (limited to 'docs/InternalsManual.rst')
| -rw-r--r-- | docs/InternalsManual.rst | 63 |
1 files changed, 42 insertions, 21 deletions
diff --git a/docs/InternalsManual.rst b/docs/InternalsManual.rst index 058c63f0afd6..af15b2e51e1c 100644 --- a/docs/InternalsManual.rst +++ b/docs/InternalsManual.rst @@ -54,7 +54,7 @@ number of source ranges that related to the diagnostic. In this section, we'll be giving examples produced by the Clang command line driver, but diagnostics can be :ref:`rendered in many different ways -<DiagnosticClient>` depending on how the ``DiagnosticClient`` interface is +<DiagnosticConsumer>` depending on how the ``DiagnosticConsumer`` interface is implemented. A representative example of a diagnostic is: .. code-block:: text @@ -188,7 +188,7 @@ Formatting a Diagnostic Argument Arguments to diagnostics are fully typed internally, and come from a couple different classes: integers, types, names, and random strings. Depending on the class of the argument, it can be optionally formatted in different ways. -This gives the ``DiagnosticClient`` information about what the argument means +This gives the ``DiagnosticConsumer`` information about what the argument means without requiring it to use a specific presentation (consider this MVC for Clang :). @@ -319,6 +319,32 @@ they should be discussed before they are added. If you are creating a lot of repetitive diagnostics and/or have an idea for a useful formatter, please bring it up on the cfe-dev mailing list. +**"sub" format** + +Example: + Given the following record definition of type ``TextSubstitution``: + + .. code-block:: text + + def select_ovl_candidate : TextSubstitution< + "%select{function|constructor}0%select{| template| %2}1">; + + which can be used as + + .. code-block:: text + + def note_ovl_candidate : Note< + "candidate %sub{select_ovl_candidate}3,2,1 not viable">; + + and will act as if it was written + ``"candidate %select{function|constructor}3%select{| template| %1}2 not viable"``. +Description: + This format specifier is used to avoid repeating strings verbatim in multiple + diagnostics. The argument to ``%sub`` must name a ``TextSubstitution`` tblgen + record. The substitution must specify all arguments used by the substitution, + and the modifier indexes in the substitution are re-numbered accordingly. The + substituted text must itself be a valid format string before substitution. + .. _internals-producing-diag: Producing the Diagnostic @@ -387,7 +413,7 @@ exactly where those parentheses would be inserted into the source code. The fix-it hints themselves describe what changes to make to the source code in an abstract manner, which the text diagnostic printer renders as a line of "insertions" below the caret line. :ref:`Other diagnostic clients -<DiagnosticClient>` might choose to render the code differently (e.g., as +<DiagnosticConsumer>` might choose to render the code differently (e.g., as markup inline) or even give the user the ability to automatically fix the problem. @@ -420,26 +446,26 @@ Fix-it hints can be created with one of three constructors: Specifies that the code in the given source ``Range`` should be removed, and replaced with the given ``Code`` string. -.. _DiagnosticClient: +.. _DiagnosticConsumer: -The ``DiagnosticClient`` Interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The ``DiagnosticConsumer`` Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once code generates a diagnostic with all of the arguments and the rest of the relevant information, Clang needs to know what to do with it. As previously mentioned, the diagnostic machinery goes through some filtering to map a severity onto a diagnostic level, then (assuming the diagnostic is not mapped -to "``Ignore``") it invokes an object that implements the ``DiagnosticClient`` +to "``Ignore``") it invokes an object that implements the ``DiagnosticConsumer`` interface with the information. It is possible to implement this interface in many different ways. For -example, the normal Clang ``DiagnosticClient`` (named +example, the normal Clang ``DiagnosticConsumer`` (named ``TextDiagnosticPrinter``) turns the arguments into strings (according to the various formatting rules), prints out the file/line/column information and the string, then prints out the line of code, the source ranges, and the caret. However, this behavior isn't required. -Another implementation of the ``DiagnosticClient`` interface is the +Another implementation of the ``DiagnosticConsumer`` interface is the ``TextDiagnosticBuffer`` class, which is used when Clang is in ``-verify`` mode. Instead of formatting and printing out the diagnostics, this implementation just captures and remembers the diagnostics as they fly by. @@ -1638,15 +1664,15 @@ 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. +parsed representation of an attribute object is an ``ParsedAttr`` 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. +``ParsedAttr`` 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 +an ``ParsedAttr``, 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 @@ -1725,8 +1751,8 @@ 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>`_ +in `include/clang/Sema/ParsedAttr.h +<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/ParsedAttr.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>`_ @@ -1823,7 +1849,7 @@ 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 +If the attribute should not be propagated 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. @@ -1861,15 +1887,10 @@ requirements. To support this feature, an attribute inheriting from 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 +attribute classes. For instance, ``ParsedAttr`` 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), set |