diff options
Diffstat (limited to 'include/clang/Basic/AttrDocs.td')
| -rw-r--r-- | include/clang/Basic/AttrDocs.td | 210 |
1 files changed, 203 insertions, 7 deletions
diff --git a/include/clang/Basic/AttrDocs.td b/include/clang/Basic/AttrDocs.td index fac6116057dc2..114a9856c5fb4 100644 --- a/include/clang/Basic/AttrDocs.td +++ b/include/clang/Basic/AttrDocs.td @@ -1408,15 +1408,17 @@ all optional, but the attribute has to have at least one clause. }]; } -def RequireConstantInitDocs : Documentation { +def ConstInitDocs : Documentation { let Category = DocCatVariable; + let Heading = "require_constant_initialization, constinit (C++20)"; let Content = [{ This attribute specifies that the variable to which it is attached is intended to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_ according to the rules of [basic.start.static]. The variable is required to have static or thread storage duration. If the initialization of the variable is not a constant initializer an error will be produced. This attribute may -only be used in C++. +only be used in C++; the ``constinit`` spelling is only accepted in C++20 +onwards. Note that in C++03 strict constant expression checking is not done. Instead the attribute reports if Clang can emit the variable as a constant, even if it's @@ -1431,6 +1433,12 @@ for constant initialization have been met. Since these requirements change between dialects and have subtle pitfalls it's important to fail fast instead of silently falling back on dynamic initialization. +The first use of the attribute on a variable must be part of, or precede, the +initializing declaration of the variable. C++20 requires the ``constinit`` +spelling of the attribute to be present on the initializing declaration if it +is used anywhere. The other spellings can be specified on a forward declaration +and omitted on a later initializing declaration. + .. code-block:: c++ // -std=c++14 @@ -1482,6 +1490,13 @@ generated when a function or its return type is marked with ``[[nodiscard]]`` potentially-evaluated discarded-value expression that is not explicitly cast to `void`. +A string literal may optionally be provided to the attribute, which will be +reproduced in any resulting diagnostics. Redeclarations using different forms +of the attribute (with or without the string literal or with different string +literal contents) are allowed. If there are redeclarations of the entity with +differing string literals, it is unspecified which one will be used by Clang +in any resulting diagnostics. + .. code-block: c++ struct [[nodiscard]] error_info { /*...*/ }; error_info enable_missile_safety_mode(); @@ -1493,6 +1508,33 @@ potentially-evaluated discarded-value expression that is not explicitly cast to } error_info &foo(); void f() { foo(); } // Does not diagnose, error_info is a reference. + +Additionally, discarded temporaries resulting from a call to a constructor +marked with ``[[nodiscard]]`` or a constructor of a type marked +``[[nodiscard]]`` will also diagnose. This also applies to type conversions that +use the annotated ``[[nodiscard]]`` constructor or result in an annotated type. + +.. code-block: c++ + struct [[nodiscard]] marked_type {/*..*/ }; + struct marked_ctor { + [[nodiscard]] marked_ctor(); + marked_ctor(int); + }; + + struct S { + operator marked_type() const; + [[nodiscard]] operator int() const; + }; + + void usages() { + marked_type(); // diagnoses. + marked_ctor(); // diagnoses. + marked_ctor(3); // Does not diagnose, int constructor isn't marked nodiscard. + + S s; + static_cast<marked_type>(s); // diagnoses + (int)s; // diagnoses + } }]; } @@ -2187,6 +2229,18 @@ to avoid false positives in other places. }]; } +def CFICanonicalJumpTableDocs : Documentation { + let Category = DocCatFunction; + let Heading = "cfi_canonical_jump_table"; + let Content = [{ +.. _langext-cfi_canonical_jump_table: + +Use ``__attribute__((cfi_canonical_jump_table))`` on a function declaration to +make the function's CFI jump table canonical. See :ref:`the CFI documentation +<cfi-canonical-jump-tables>` for more details. + }]; +} + def DocCatTypeSafety : DocumentationCategory<"Type Safety Checking"> { let Content = [{ Clang supports additional attributes to enable checking type safety properties @@ -2504,6 +2558,30 @@ manipulating bits of the enumerator when issuing warnings. }]; } +def AsmLabelDocs : Documentation { + let Category = DocCatDecl; + let Content = [{ +This attribute can be used on a function or variable to specify its symbol name. + +On some targets, all C symbols are prefixed by default with a single character, typically ``_``. This was done historically to distinguish them from symbols used by other languages. (This prefix is also added to the standard Itanium C++ ABI prefix on "mangled" symbol names, so that e.g. on such targets the true symbol name for a C++ variable declared as ``int cppvar;`` would be ``__Z6cppvar``; note the two underscores.) This prefix is *not* added to the symbol names specified by the ``asm`` attribute; programmers wishing to match a C symbol name must compensate for this. + +For example, consider the following C code: + +.. code-block:: c + + int var1 asm("altvar") = 1; // "altvar" in symbol table. + int var2 = 1; // "_var2" in symbol table. + + void func1(void) asm("altfunc"); + void func1(void) {} // "altfunc" in symbol table. + void func2(void) {} // "_func2" in symbol table. + +Clang's implementation of this attribute is compatible with GCC's, `documented here <https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html>`_. + +While it is possible to use this attribute to name a special symbol used internally by the compiler, such as an LLVM intrinsic, this is neither recommended nor supported and may cause the compiler to crash or miscompile. Users who wish to gain access to intrinsic behavior are strongly encouraged to request new builtin functions. + }]; +} + def EnumExtensibilityDocs : Documentation { let Category = DocCatDecl; let Content = [{ @@ -2583,7 +2661,7 @@ is retained by the return value of the annotated function It is only supported in C++. This attribute provides an experimental implementation of the facility -described in the C++ committee paper [http://wg21.link/p0936r0](P0936R0), +described in the C++ committee paper `P0936R0 <http://wg21.link/p0936r0>`_, and is subject to change as the design of the corresponding functionality changes. }]; @@ -2709,9 +2787,10 @@ def LoopHintDocs : Documentation { let Content = [{ The ``#pragma clang loop`` directive allows loop optimization hints to be specified for the subsequent loop. The directive allows pipelining to be -disabled, or vectorization, interleaving, and unrolling to be enabled or disabled. -Vector width, interleave count, unrolling count, and the initiation interval -for pipelining can be explicitly specified. See `language extensions +disabled, or vectorization, vector predication, interleaving, and unrolling to +be enabled or disabled. Vector width, vector predication, interleave count, +unrolling count, and the initiation interval for pipelining can be explicitly +specified. See `language extensions <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ for details. }]; @@ -3129,6 +3208,55 @@ The syntax of the declare target directive is as follows: #pragma omp declare target new-line declarations-definition-seq #pragma omp end declare target new-line + +or + + .. code-block:: c + + #pragma omp declare target (extended-list) new-line + +or + + .. code-block:: c + + #pragma omp declare target clause[ [,] clause ... ] new-line + +where clause is one of the following: + + + .. code-block:: c + + to(extended-list) + link(list) + device_type(host | nohost | any) + }]; +} + +def OMPDeclareVariantDocs : Documentation { + let Category = DocCatFunction; + let Heading = "#pragma omp declare variant"; + let Content = [{ +The `declare variant` directive declares a specialized variant of a base + function and specifies the context in which that specialized variant is used. + The declare variant directive is a declarative directive. +The syntax of the `declare variant` construct is as follows: + + .. code-block:: none + + #pragma omp declare variant(variant-func-id) clause new-line + [#pragma omp declare variant(variant-func-id) clause new-line] + [...] + function definition or declaration + +where clause is one of the following: + + .. code-block:: none + + match(context-selector-specification) + +and where `variant-func-id` is the name of a function variant that is either a + base language identifier or, for C++, a template-id. + }]; } @@ -4194,4 +4322,72 @@ be accessed on both device side and host side. It has external linkage and is not initialized on device side. It has internal linkage and is initialized by the initializer on host side. }]; -}
\ No newline at end of file +} + +def LifetimeOwnerDocs : Documentation { + let Category = DocCatDecl; + let Content = [{ +.. Note:: This attribute is experimental and its effect on analysis is subject to change in + a future version of clang. + +The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an +object of type ``T``: + +.. code-block:: c++ + + class [[gsl::Owner(int)]] IntOwner { + private: + int value; + public: + int *getInt() { return &value; } + }; + +The argument ``T`` is optional and is ignored. +This attribute may be used by analysis tools and has no effect on code +generation. + +See Pointer_ for an example. +}]; +} + +def LifetimePointerDocs : Documentation { + let Category = DocCatDecl; + let Content = [{ +.. Note:: This attribute is experimental and its effect on analysis is subject to change in + a future version of clang. + +The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave +like pointers to an object of type ``T``: + +.. code-block:: c++ + + class [[gsl::Pointer(int)]] IntPointer { + private: + int *valuePointer; + public: + int *getInt() { return &valuePointer; } + }; + +The argument ``T`` is optional and is ignored. +This attribute may be used by analysis tools and has no effect on code +generation. + +Example: +When constructing an instance of a class annotated like this (a Pointer) from +an instance of a class annotated with ``[[gsl::Owner]]`` (an Owner), +then the analysis will consider the Pointer to point inside the Owner. +When the Owner's lifetime ends, it will consider the Pointer to be dangling. + +.. code-block:: c++ + + int f() { + IntPointer P; + if (true) { + IntOwner O(7); + P = IntPointer(O); // P "points into" O + } // P is dangling + return P.get(); // error: Using a dangling Pointer. + } + +}]; +} |