AttrDocTable.inc source code [llvm_projects/build/tools/clang/lib/AST/AttrDocTable.inc]

1	/===- TableGen'erated file -------------------------------------- C++ --===\
2	\| \|
3	\| Clang attribute documentation \|
4	\| \|
5	\| Automatically generated file, do not edit! \|
6	\| From: Attr.td \|
7	\| \|
8	\===----------------------------------------------------------------------===/
9
10
11	static const char AttrDoc_AArch64SVEPcs[] = R"reST(On AArch64 targets, this attribute changes the calling convention of a
12	function to preserve additional Scalable Vector registers and Scalable
13	Predicate registers relative to the default calling convention used for
14	AArch64.
15
16	This means it is more efficient to call such functions from code that performs
17	extensive scalable vector and scalable predicate calculations, because fewer
18	live SVE registers need to be saved. This property makes it well-suited for SVE
19	math library functions, which are typically leaf functions that require a small
20	number of registers.
21
22	However, using this attribute also means that it is more expensive to call
23	a function that adheres to the default calling convention from within such
24	a function. Therefore, it is recommended that this attribute is only used
25	for leaf functions.
26
27	For more information, see the documentation for `aarch64_sve_pcs` in the
28	ARM C Language Extension (ACLE) documentation.
29
30	.. _`aarch64_sve_pcs`: https://github.com/ARM-software/acle/blob/main/main/acle.md#scalable-vector-extension-procedure-call-standard-attribute)reST";
31
32	static const char AttrDoc_AArch64VectorPcs[] = R"reST(On AArch64 targets, this attribute changes the calling convention of a
33	function to preserve additional floating-point and Advanced SIMD registers
34	relative to the default calling convention used for AArch64.
35
36	This means it is more efficient to call such functions from code that performs
37	extensive floating-point and vector calculations, because fewer live SIMD and FP
38	registers need to be saved. This property makes it well-suited for e.g.
39	floating-point or vector math library functions, which are typically leaf
40	functions that require a small number of registers.
41
42	However, using this attribute also means that it is more expensive to call
43	a function that adheres to the default calling convention from within such
44	a function. Therefore, it is recommended that this attribute is only used
45	for leaf functions.
46
47	For more information, see the documentation for `aarch64_vector_pcs`_ on
48	the Arm Developer website.
49
50	.. _`aarch64_vector_pcs`: https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi)reST";
51
52	static const char AttrDoc_AMDGPUFlatWorkGroupSize[] = R"reST(The flat work-group size is the number of work-items in the work-group size
53	specified when the kernel is dispatched. It is the product of the sizes of the
54	x, y, and z dimension of the work-group.
55
56	Clang supports the
57	``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
58	AMDGPU target. This attribute may be attached to a kernel function definition
59	and is an optimization hint.
60
61	``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
62	parameter specifies the maximum flat work-group size (must be greater than
63	``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
64	as ``<min>, <max>`` implies the default behavior (``128, 256``).
65
66	If specified, the AMDGPU target backend might be able to produce better machine
67	code for barriers and perform scratch promotion by estimating available group
68	segment size.
69
70	An error will be given if:
71	- Specified values violate subtarget specifications;
72	- Specified values are not compatible with values provided through other
73	attributes.)reST";
74
75	static const char AttrDoc_AMDGPUMaxNumWorkGroups[] = R"reST(This attribute specifies the max number of work groups when the kernel
76	is dispatched.
77
78	Clang supports the
79	``__attribute__((amdgpu_max_num_work_groups(<x>, <y>, <z>)))`` or
80	``[[clang::amdgpu_max_num_work_groups(<x>, <y>, <z>)]]`` attribute for the
81	AMDGPU target. This attribute may be attached to HIP or OpenCL kernel function
82	definitions and is an optimization hint.
83
84	The ``<x>`` parameter specifies the maximum number of work groups in the x dimension.
85	Similarly ``<y>`` and ``<z>`` are for the y and z dimensions respectively.
86	Each of the three values must be greater than 0 when provided. The ``<x>`` parameter
87	is required, while ``<y>`` and ``<z>`` are optional with default value of 1.
88
89	If specified, the AMDGPU target backend might be able to produce better machine
90	code.
91
92	An error will be given if:
93	- Specified values violate subtarget specifications;
94	- Specified values are not compatible with values provided through other
95	attributes.)reST";
96
97	static const char AttrDoc_AMDGPUNumSGPR[] = R"reST(Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
98	``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
99	target. These attributes may be attached to a kernel function definition and are
100	an optimization hint.
101
102	If these attributes are specified, then the AMDGPU target backend will attempt
103	to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
104	number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
105	allocation requirements or constraints of the subtarget. Passing ``0`` as
106	``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
107
108	These attributes can be used to test the AMDGPU target backend. It is
109	recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
110	resources such as SGPRs and VGPRs since it is aware of the limits for different
111	subtargets.
112
113	An error will be given if:
114	- Specified values violate subtarget specifications;
115	- Specified values are not compatible with values provided through other
116	attributes;
117	- The AMDGPU target backend is unable to create machine code that can meet the
118	request.)reST";
119
120	static const char AttrDoc_AMDGPUNumVGPR[] = R"reST(Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
121	``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
122	target. These attributes may be attached to a kernel function definition and are
123	an optimization hint.
124
125	If these attributes are specified, then the AMDGPU target backend will attempt
126	to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
127	number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
128	allocation requirements or constraints of the subtarget. Passing ``0`` as
129	``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
130
131	These attributes can be used to test the AMDGPU target backend. It is
132	recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
133	resources such as SGPRs and VGPRs since it is aware of the limits for different
134	subtargets.
135
136	An error will be given if:
137	- Specified values violate subtarget specifications;
138	- Specified values are not compatible with values provided through other
139	attributes;
140	- The AMDGPU target backend is unable to create machine code that can meet the
141	request.)reST";
142
143	static const char AttrDoc_AMDGPUWavesPerEU[] = R"reST(A compute unit (CU) is responsible for executing the wavefronts of a work-group.
144	It is composed of one or more execution units (EU), which are responsible for
145	executing the wavefronts. An EU can have enough resources to maintain the state
146	of more than one executing wavefront. This allows an EU to hide latency by
147	switching between wavefronts in a similar way to symmetric multithreading on a
148	CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
149	resources used by a single wavefront have to be limited. For example, the number
150	of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
151	but can result in having to spill some register state to memory.
152
153	Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
154	attribute for the AMDGPU target. This attribute may be attached to a kernel
155	function definition and is an optimization hint.
156
157	``<min>`` parameter specifies the requested minimum number of waves per EU, and
158	optional ``<max>`` parameter specifies the requested maximum number of waves
159	per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted,
160	then there is no restriction on the maximum number of waves per EU other than
161	the one dictated by the hardware for which the kernel is compiled. Passing
162	``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
163
164	If specified, this attribute allows an advanced developer to tune the number of
165	wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
166	target backend can use this information to limit resources, such as number of
167	SGPRs, number of VGPRs, size of available group and private memory segments, in
168	such a way that guarantees that at least ``<min>`` wavefronts and at most
169	``<max>`` wavefronts are able to fit within the resources of an EU. Requesting
170	more wavefronts can hide memory latency but limits available registers which
171	can result in spilling. Requesting fewer wavefronts can help reduce cache
172	thrashing, but can reduce memory latency hiding.
173
174	This attribute controls the machine code generated by the AMDGPU target backend
175	to ensure it is capable of meeting the requested values. However, when the
176	kernel is executed, there may be other reasons that prevent meeting the request,
177	for example, there may be wavefronts from other kernels executing on the EU.
178
179	An error will be given if:
180	- Specified values violate subtarget specifications;
181	- Specified values are not compatible with values provided through other
182	attributes;
183
184	The AMDGPU target backend will emit a warning whenever it is unable to
185	create machine code that meets the request.)reST";
186
187	static const char AttrDoc_ARMInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
188	ARM targets. This attribute may be attached to a function definition and
189	instructs the backend to generate appropriate function entry/exit code so that
190	it can be used directly as an interrupt service routine.
191
192	The parameter passed to the interrupt attribute is optional, but if
193	provided it must be a string literal with one of the following values: "IRQ",
194	"FIQ", "SWI", "ABORT", "UNDEF".
195
196	The semantics are as follows:
197
198	- If the function is AAPCS, Clang instructs the backend to realign the stack to
199	8 bytes on entry. This is a general requirement of the AAPCS at public
200	interfaces, but may not hold when an exception is taken. Doing this allows
201	other AAPCS functions to be called.
202	- If the CPU is M-class this is all that needs to be done since the architecture
203	itself is designed in such a way that functions obeying the normal AAPCS ABI
204	constraints are valid exception handlers.
205	- If the CPU is not M-class, the prologue and epilogue are modified to save all
206	non-banked registers that are used, so that upon return the user-mode state
207	will not be corrupted. Note that to avoid unnecessary overhead, only
208	general-purpose (integer) registers are saved in this way. If VFP operations
209	are needed, that state must be saved manually.
210
211	Specifically, interrupt kinds other than "FIQ" will save all core registers
212	except "lr" and "sp". "FIQ" interrupts will save r0-r7.
213	- If the CPU is not M-class, the return instruction is changed to one of the
214	canonical sequences permitted by the architecture for exception return. Where
215	possible the function itself will make the necessary "lr" adjustments so that
216	the "preferred return address" is selected.
217
218	Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
219	handler, where the offset from "lr" to the preferred return address depends on
220	the execution state of the code which generated the exception. In this case
221	a sequence equivalent to "movs pc, lr" will be used.)reST";
222
223	static const char AttrDoc_ARMInterruptSaveFP[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt_save_fp("TYPE")))``
224	on ARM targets. This attribute behaves the same way as the ARM interrupt
225	attribute, except the general purpose floating point registers are also saved,
226	along with FPEXC and FPSCR. Note, even on M-class CPUs, where the floating
227	point context can be automatically saved depending on the FPCCR, the general
228	purpose floating point registers will be saved.)reST";
229
230	static const char AttrDoc_ARMSaveFP[] = R"reST()reST";
231
232	static const char AttrDoc_AVRInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
233	AVR targets. This attribute may be attached to a function definition and instructs
234	the backend to generate appropriate function entry/exit code so that it can be used
235	directly as an interrupt service routine.
236
237	On the AVR, the hardware globally disables interrupts when an interrupt is executed.
238	The first instruction of an interrupt handler declared with this attribute is a SEI
239	instruction to re-enable interrupts. See also the signal attribute that
240	does not insert a SEI instruction.)reST";
241
242	static const char AttrDoc_AVRSignal[] = R"reST(Clang supports the GNU style ``__attribute__((signal))`` attribute on
243	AVR targets. This attribute may be attached to a function definition and instructs
244	the backend to generate appropriate function entry/exit code so that it can be used
245	directly as an interrupt service routine.
246
247	Interrupt handler functions defined with the signal attribute do not re-enable interrupts.)reST";
248
249	static const char AttrDoc_AbiTag[] = R"reST(The ``abi_tag`` attribute can be applied to a function, variable, class or
250	inline namespace declaration to modify the mangled name of the entity. It gives
251	the ability to distinguish between different versions of the same entity but
252	with different ABI versions supported. For example, a newer version of a class
253	could have a different set of data members and thus have a different size. Using
254	the ``abi_tag`` attribute, it is possible to have different mangled names for
255	a global variable of the class type. Therefore, the old code could keep using
256	the old mangled name and the new code will use the new mangled name with tags.)reST";
257
258	static const char AttrDoc_AcquireCapability[] = R"reST(Marks a function as acquiring a capability.)reST";
259
260	static const char AttrDoc_AcquireHandle[] = R"reST(If this annotation is on a function or a function type it is assumed to return
261	a new handle. In case this annotation is on an output parameter,
262	the function is assumed to fill the corresponding argument with a new
263	handle. The attribute requires a string literal argument which used to
264	identify the handle with later uses of ``use_handle`` or
265	``release_handle``.
266
267	.. code-block:: c++
268
269	// Output arguments from Zircon.
270	zx_status_t zx_socket_create(uint32_t options,
271	zx_handle_t __attribute__((acquire_handle("zircon"))) * out0,
272	zx_handle_t* out1 [[clang::acquire_handle("zircon")]]);
273
274
275	// Returned handle.
276	[[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
277	int open(const char *path, int oflag, ... ) __attribute__((acquire_handle("tag")));)reST";
278
279	static const char AttrDoc_AcquiredAfter[] = R"reST(No documentation.)reST";
280
281	static const char AttrDoc_AcquiredBefore[] = R"reST(No documentation.)reST";
282
283	static const char AttrDoc_AddressSpace[] = R"reST(.. Note:: This attribute is mainly intended to be used by target headers
284	provided by the toolchain. End users should prefer the documented, named
285	address space annotations for their platform, such as the
286	`OpenCL address spaces`_, ``__global__``, ``__local__``, or something else.
287
288	The ``address_space`` attribute functions as a type qualifier that allows the
289	programmer to specify the address space for a pointer or reference type.
290	Qualified pointer types are considered distinct types for the purposes of
291	overload resolution. The attribute takes a single, non-negative integer
292	constant expression identifying the address space. For example:
293
294	.. code-block:: c
295
296	int * __attribute__((address_space(1))) ptr;
297
298	void foo(__attribute__((address_space(2))) float *buf);
299
300
301	Only one address space qualifier may be applied to a given pointer or reference
302	type. Where address spaces are allowed (e.g., variables, parameters, return
303	types) and what values are valid depends on the target and language mode.
304
305	The meaning of each value is defined by the target; multiple address spaces are
306	used in environments such as OpenCL, CUDA, HIP, and other GPU programming
307	models to distinguish global, local, constant, and private memory. See for
308	example the address spaces defined in the `NVPTX Usage Guide`_ and the
309	`AMDGPU Usage Guide`_.
310
311	.. _`NVPTX Usage Guide`: https://llvm.org/docs/NVPTXUsage.html#address-spaces
312	.. _`AMDGPU Usage Guide`: https://llvm.org/docs/AMDGPUUsage.html#address-spaces
313
314	Address spaces may partially overlap or be entirely distinct. The compiler may
315	reject attempts to convert between distinct, incompatible address spaces.
316	Pointer width may vary between different address spaces, so some explicit casts
317	may truncate.
318
319	For more information, refer to `ISO TR18037`_, which covers embedded C language
320	extensions. Section 5 covers named address spaces.
321
322	.. _`ISO TR18037`: https://standards.iso.org/ittf/PubliclyAvailableStandards/c051126_ISO_IEC_TR_18037_2008.zip)reST";
323
324	static const char AttrDoc_Alias[] = R"reST(No documentation.)reST";
325
326	static const char AttrDoc_AlignMac68k[] = R"reST()reST";
327
328	static const char AttrDoc_AlignNatural[] = R"reST()reST";
329
330	static const char AttrDoc_AlignValue[] = R"reST(The align_value attribute can be added to the typedef of a pointer type or the
331	declaration of a variable of pointer or reference type. It specifies that the
332	pointer will point to, or the reference will bind to, only objects with at
333	least the provided alignment. This alignment value must be some positive power
334	of 2.
335
336	.. code-block:: c
337
338	typedef double * aligned_double_ptr __attribute__((align_value(64)));
339	void foo(double & x __attribute__((align_value(128))),
340	aligned_double_ptr y) { ... }
341
342	If the pointer value does not have the specified alignment at runtime, the
343	behavior of the program is undefined.)reST";
344
345	static const char AttrDoc_Aligned[] = R"reST(No documentation.)reST";
346
347	static const char AttrDoc_AllocAlign[] = R"reST(Use ``__attribute__((alloc_align(<alignment>))`` on a function
348	declaration to specify that the return value of the function (which must be a
349	pointer type) is at least as aligned as the value of the indicated parameter. The
350	parameter is given by its index in the list of formal parameters; the first
351	parameter has index 1 unless the function is a C++ non-static member function,
352	in which case the first parameter has index 2 to account for the implicit ``this``
353	parameter.
354
355	.. code-block:: c++
356
357	// The returned pointer has the alignment specified by the first parameter.
358	void *a(size_t align) __attribute__((alloc_align(1)));
359
360	// The returned pointer has the alignment specified by the second parameter.
361	void b(void v, size_t align) __attribute__((alloc_align(2)));
362
363	// The returned pointer has the alignment specified by the second visible
364	// parameter, however it must be adjusted for the implicit 'this' parameter.
365	void Foo::b(void v, size_t align) __attribute__((alloc_align(3)));
366
367	Note that this attribute merely informs the compiler that a function always
368	returns a sufficiently aligned pointer. It does not cause the compiler to
369	emit code to enforce that alignment. The behavior is undefined if the returned
370	pointer is not sufficiently aligned.)reST";
371
372	static const char AttrDoc_AllocSize[] = R"reST(The ``alloc_size`` attribute can be placed on functions that return pointers in
373	order to hint to the compiler how many bytes of memory will be available at the
374	returned pointer. ``alloc_size`` takes one or two arguments.
375
376	- ``alloc_size(N)`` implies that argument number N equals the number of
377	available bytes at the returned pointer.
378	- ``alloc_size(N, M)`` implies that the product of argument number N and
379	argument number M equals the number of available bytes at the returned
380	pointer.
381
382	Argument numbers are 1-based.
383
384	An example of how to use ``alloc_size``
385
386	.. code-block:: c
387
388	void *my_malloc(int a) __attribute__((alloc_size(1)));
389	void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
390
391	int main() {
392	void *const p = my_malloc(100);
393	assert(__builtin_object_size(p, 0) == 100);
394	void *const a = my_calloc(20, 5);
395	assert(__builtin_object_size(a, 0) == 100);
396	}
397
398	When ``-Walloc-size`` is enabled, this attribute allows the compiler to
399	diagnose cases when the allocated memory is insufficient for the size of the
400	type the returned pointer is cast to.
401
402	.. code-block:: c
403
404	void *my_malloc(int a) __attribute__((alloc_size(1)));
405	void consumer_func(int *);
406
407	int main() {
408	int *ptr = my_malloc(sizeof(int)); // no warning
409	int *w = my_malloc(1); // warning: allocation of insufficient size '1' for type 'int' with size '4'
410	consumer_func(my_malloc(1)); // warning: allocation of insufficient size '1' for type 'int' with size '4'
411	}
412
413	.. Note:: This attribute works differently in clang than it does in GCC.
414	Specifically, clang will only trace ``const`` pointers (as above); we give up
415	on pointers that are not marked as ``const``. In the vast majority of cases,
416	this is unimportant, because LLVM has support for the ``alloc_size``
417	attribute. However, this may cause mildly unintuitive behavior when used with
418	other attributes, such as ``enable_if``.)reST";
419
420	static const char AttrDoc_Allocating[] = R"reST(Declares that a function potentially allocates heap memory, and prevents any potential inference
421	of ``nonallocating`` by the compiler.)reST";
422
423	static const char AttrDoc_AlwaysDestroy[] = R"reST(The ``always_destroy`` attribute specifies that a variable with static or thread
424	storage duration should have its exit-time destructor run. This attribute is the
425	default unless clang was invoked with -fno-c++-static-destructors.
426
427	If a variable is explicitly declared with this attribute, Clang will silence
428	otherwise applicable ``-Wexit-time-destructors`` warnings.)reST";
429
430	static const char AttrDoc_AlwaysInline[] = R"reST(Inlining heuristics are disabled and inlining is always attempted regardless of
431	optimization level.
432
433	``[[clang::always_inline]]`` spelling can be used as a statement attribute; other
434	spellings of the attribute are not supported on statements. If a statement is
435	marked ``[[clang::always_inline]]`` and contains calls, the compiler attempts
436	to inline those calls.
437
438	.. code-block:: c
439
440	int example(void) {
441	int i;
442	[[clang::always_inline]] foo(); // attempts to inline foo
443	[[clang::always_inline]] i = bar(); // attempts to inline bar
444	[[clang::always_inline]] return f(42, baz(bar())); // attempts to inline everything
445	}
446
447	A declaration statement, which is a statement, is not a statement that can have an
448	attribute associated with it (the attribute applies to the declaration, not the
449	statement in that case). So this use case will not work:
450
451	.. code-block:: c
452
453	int example(void) {
454	[[clang::always_inline]] int i = bar();
455	return i;
456	}
457
458	This attribute does not guarantee that inline substitution actually occurs.
459
460	<ins>Note: applying this attribute to a coroutine at the `-O0` optimization level
461	has no effect; other optimization levels may only partially inline and result in a
462	diagnostic.</ins>
463
464	See also `the Microsoft Docs on Inline Functions`_, `the GCC Common Function
465	Attribute docs`_, and `the GCC Inline docs`_.
466
467	.. _the Microsoft Docs on Inline Functions: https://docs.microsoft.com/en-us/cpp/cpp/inline-functions-cpp
468	.. _the GCC Common Function Attribute docs: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
469	.. _the GCC Inline docs: https://gcc.gnu.org/onlinedocs/gcc/Inline.html)reST";
470
471	static const char AttrDoc_AnalyzerNoReturn[] = R"reST(No documentation.)reST";
472
473	static const char AttrDoc_Annotate[] = R"reST(No documentation.)reST";
474
475	static const char AttrDoc_AnnotateType[] = R"reST(This attribute is used to add annotations to types, typically for use by static
476	analysis tools that are not integrated into the core Clang compiler (e.g.,
477	Clang-Tidy checks or out-of-tree Clang-based tools). It is a counterpart to the
478	`annotate` attribute, which serves the same purpose, but for declarations.
479
480	The attribute takes a mandatory string literal argument specifying the
481	annotation category and an arbitrary number of optional arguments that provide
482	additional information specific to the annotation category. The optional
483	arguments must be constant expressions of arbitrary type.
484
485	For example:
486
487	.. code-block:: c++
488
489	int* [[clang::annotate_type("category1", "foo", 1)]] f(int[[clang::annotate_type("category2")]] *);
490
491	The attribute does not have any effect on the semantics of the type system,
492	neither type checking rules, nor runtime semantics. In particular:
493
494	- ``std::is_same<T, T [[clang::annotate_type("foo")]]>`` is true for all types
495	``T``.
496
497	- It is not permissible for overloaded functions or template specializations
498	to differ merely by an ``annotate_type`` attribute.
499
500	- The presence of an ``annotate_type`` attribute will not affect name
501	mangling.)reST";
502
503	static const char AttrDoc_AnyX86Interrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt))`` attribute on X86
504	targets. This attribute may be attached to a function definition and instructs
505	the backend to generate appropriate function entry/exit code so that it can be
506	used directly as an interrupt service routine.
507
508	Interrupt handlers have access to the stack frame pushed onto the stack by the processor,
509	and return using the ``IRET`` instruction. All registers in an interrupt handler are callee-saved.
510	Exception handlers also have access to the error code pushed onto the stack by the processor,
511	when applicable.
512
513	An interrupt handler must take the following arguments:
514
515	.. code-block:: c
516
517	__attribute__ ((interrupt))
518	void f (struct stack_frame *frame) {
519	...
520	}
521
522	Where ``struct stack_frame`` is a suitable struct matching the stack frame pushed by the
523	processor.
524
525	An exception handler must take the following arguments:
526
527	.. code-block:: c
528
529	__attribute__ ((interrupt))
530	void g (struct stack_frame *frame, unsigned long code) {
531	...
532	}
533
534	On 32-bit targets, the ``code`` argument should be of type ``unsigned int``.
535
536	Exception handlers should only be used when an error code is pushed by the processor.
537	Using the incorrect handler type will crash the system.
538
539	Interrupt and exception handlers cannot be called by other functions and must have return type ``void``.
540
541	Interrupt and exception handlers should only call functions with the 'no_caller_saved_registers'
542	attribute, or should be compiled with the '-mgeneral-regs-only' flag to avoid saving unused
543	non-GPR registers.)reST";
544
545	static const char AttrDoc_AnyX86NoCallerSavedRegisters[] = R"reST(Use this attribute to indicate that the specified function has no
546	caller-saved registers. That is, all registers are callee-saved except for
547	registers used for passing parameters to the function or returning parameters
548	from the function.
549	The compiler saves and restores any modified registers that were not used for
550	passing or returning arguments to the function.
551
552	The user can call functions specified with the 'no_caller_saved_registers'
553	attribute from an interrupt handler without saving and restoring all
554	call-clobbered registers.
555
556	Functions specified with the 'no_caller_saved_registers' attribute should only
557	call other functions with the 'no_caller_saved_registers' attribute, or should be
558	compiled with the '-mgeneral-regs-only' flag to avoid saving unused non-GPR registers.
559
560	Note that 'no_caller_saved_registers' attribute is not a calling convention.
561	In fact, it only overrides the decision of which registers should be saved by
562	the caller, but not how the parameters are passed from the caller to the callee.
563
564	For example:
565
566	.. code-block:: c
567
568	__attribute__ ((no_caller_saved_registers, fastcall))
569	void f (int arg1, int arg2) {
570	...
571	}
572
573	In this case parameters 'arg1' and 'arg2' will be passed in registers.
574	In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
575	register parameters. However, it will not assume any scratch registers and
576	should save and restore any modified registers except for ECX and EDX.)reST";
577
578	static const char AttrDoc_AnyX86NoCfCheck[] = R"reST(Jump Oriented Programming attacks rely on tampering with addresses used by
579	indirect call / jmp, e.g. redirect control-flow to non-programmer
580	intended bytes in the binary.
581	X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
582	Enforcement Technology (CET). IBT instruments ENDBR instructions used to
583	specify valid targets of indirect call / jmp.
584	The ``nocf_check`` attribute has two roles:
585	1. Appertains to a function - do not add ENDBR instruction at the beginning of
586	the function.
587	2. Appertains to a function pointer - do not track the target function of this
588	pointer (by adding nocf_check prefix to the indirect-call instruction).)reST";
589
590	static const char AttrDoc_ArcWeakrefUnavailable[] = R"reST(No documentation.)reST";
591
592	static const char AttrDoc_ArgumentWithTypeTag[] = R"reST(Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
593	type_tag_idx)))`` on a function declaration to specify that the function
594	accepts a type tag that determines the type of some other argument.
595
596	This attribute is primarily useful for checking arguments of variadic functions
597	(``pointer_with_type_tag`` can be used in most non-variadic cases).
598
599	In the attribute prototype above:
600	* ``arg_kind`` is an identifier that should be used when annotating all
601	applicable type tags.
602	* ``arg_idx`` provides the position of a function argument. The expected type of
603	this function argument will be determined by the function argument specified
604	by ``type_tag_idx``. In the code example below, "3" means that the type of the
605	function's third argument will be determined by ``type_tag_idx``.
606	* ``type_tag_idx`` provides the position of a function argument. This function
607	argument will be a type tag. The type tag will determine the expected type of
608	the argument specified by ``arg_idx``. In the code example below, "2" means
609	that the type tag associated with the function's second argument should agree
610	with the type of the argument specified by ``arg_idx``.
611
612	For example:
613
614	.. code-block:: c++
615
616	int fcntl(int fd, int cmd, ...)
617	__attribute__(( argument_with_type_tag(fcntl,3,2) ));
618	// The function's second argument will be a type tag; this type tag will
619	// determine the expected type of the function's third argument.)reST";
620
621	static const char AttrDoc_ArmAgnostic[] = R"reST(The ``__arm_agnostic`` keyword applies to prototyped function types and
622	affects the function's calling convention for a given state S. This
623	attribute allows the user to describe a function that preserves S, without
624	requiring the function to share S with its callers and without making
625	the assumption that S exists.
626
627	If a function has the ``__arm_agnostic(S)`` attribute and calls a function
628	without this attribute, then the function's object code will contain code
629	to preserve state S. Otherwise, the function's object code will be the same
630	as if it did not have the attribute.
631
632	The attribute takes string arguments to describe state S. The supported
633	states are:
634
635	* ``"sme_za_state"`` for state enabled by PSTATE.ZA, such as ZA and ZT0.
636
637	The attribute ``__arm_agnostic("sme_za_state")`` cannot be used in conjunction
638	with ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` or
639	``__arm_preserves(S)`` where state S describes state enabled by PSTATE.ZA,
640	such as "za" or "zt0".)reST";
641
642	static const char AttrDoc_ArmBuiltinAlias[] = R"reST(This attribute is used in the implementation of the ACLE intrinsics.
643	It allows the intrinsic functions to
644	be declared using the names defined in ACLE, and still be recognized
645	as clang builtins equivalent to the underlying name. For example,
646	``arm_mve.h`` declares the function ``vaddq_u32`` with
647	``__attribute__((__clang_arm_mve_alias(__builtin_arm_mve_vaddq_u32)))``,
648	and similarly, one of the type-overloaded declarations of ``vaddq``
649	will have the same attribute. This ensures that both functions are
650	recognized as that clang builtin, and in the latter case, the choice
651	of which builtin to identify the function as can be deferred until
652	after overload resolution.
653
654	This attribute can only be used to set up the aliases for certain Arm
655	intrinsic functions; it is intended for use only inside ``arm_*.h``
656	and is not a general mechanism for declaring arbitrary aliases for
657	clang builtin functions.
658
659	In order to avoid duplicating the attribute definitions for similar
660	purpose for other architecture, there is a general form for the
661	attribute `clang_builtin_alias`.)reST";
662
663	static const char AttrDoc_ArmIn[] = R"reST(The ``__arm_in`` keyword applies to prototyped function types and specifies
664	that the function shares a given state S with its caller. For ``__arm_in``, the
665	function takes the state S as input and returns with the state S unchanged.
666
667	The attribute takes string arguments to instruct the compiler which state
668	is shared. The supported states for S are:
669
670	* ``"za"`` for Matrix Storage (requires SME)
671
672	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
673	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
674
675	static const char AttrDoc_ArmInOut[] = R"reST(The ``__arm_inout`` keyword applies to prototyped function types and specifies
676	that the function shares a given state S with its caller. For ``__arm_inout``,
677	the function takes the state S as input and returns new state for S.
678
679	The attribute takes string arguments to instruct the compiler which state
680	is shared. The supported states for S are:
681
682	* ``"za"`` for Matrix Storage (requires SME)
683
684	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
685	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
686
687	static const char AttrDoc_ArmLocallyStreaming[] = R"reST(The ``__arm_locally_streaming`` keyword applies to function declarations
688	and specifies that all the statements in the function are executed in
689	streaming mode. This means that:
690
691	* the function requires that the target processor implements the Scalable Matrix
692	Extension (SME).
693
694	* the program automatically puts the machine into streaming mode before
695	executing the statements and automatically restores the previous mode
696	afterwards.
697
698	Clang manages PSTATE.SM automatically; it is not the source code's
699	responsibility to do this. For example, Clang will emit code to enable
700	streaming mode at the start of the function, and disable streaming mode
701	at the end of the function.)reST";
702
703	static const char AttrDoc_ArmMveStrictPolymorphism[] = R"reST(This attribute is used in the implementation of the ACLE intrinsics for the Arm
704	MVE instruction set. It is used to define the vector types used by the MVE
705	intrinsics.
706
707	Its effect is to modify the behavior of a vector type with respect to function
708	overloading. If a candidate function for overload resolution has a parameter
709	type with this attribute, then the selection of that candidate function will be
710	disallowed if the actual argument can only be converted via a lax vector
711	conversion. The aim is to prevent spurious ambiguity in ARM MVE polymorphic
712	intrinsics.
713
714	.. code-block:: c++
715
716	void overloaded(uint16x8_t vector, uint16_t scalar);
717	void overloaded(int32x4_t vector, int32_t scalar);
718	uint16x8_t myVector;
719	uint16_t myScalar;
720
721	// myScalar is promoted to int32_t as a side effect of the addition,
722	// so if lax vector conversions are considered for myVector, then
723	// the two overloads are equally good (one argument conversion
724	// each). But if the vector has the __clang_arm_mve_strict_polymorphism
725	// attribute, only the uint16x8_t,uint16_t overload will match.
726	overloaded(myVector, myScalar + 1);
727
728	However, this attribute does not prohibit lax vector conversions in contexts
729	other than overloading.
730
731	.. code-block:: c++
732
733	uint16x8_t function();
734
735	// This is still permitted with lax vector conversion enabled, even
736	// if the vector types have __clang_arm_mve_strict_polymorphism
737	int32x4_t result = function();)reST";
738
739	static const char AttrDoc_ArmNew[] = R"reST(The ``__arm_new`` keyword applies to function declarations and specifies
740	that the function will create a new scope for state S.
741
742	The attribute takes string arguments to instruct the compiler for which state
743	to create new scope. The supported states for S are:
744
745	* ``"za"`` for Matrix Storage (requires SME)
746
747	For state ``"za"``, this means that:
748
749	* the function requires that the target processor implements the Scalable Matrix
750	Extension (SME).
751
752	* the function will commit any lazily saved ZA data.
753
754	* the function will create a new ZA context and enable PSTATE.ZA.
755
756	* the function will disable PSTATE.ZA (by setting it to 0) before returning.
757
758	For ``__arm_new("za")`` functions Clang will set up the ZA context automatically
759	on entry to the function and disable it before returning. For example, if ZA is
760	in a dormant state Clang will generate the code to commit a lazy-save and set up
761	a new ZA state before executing user code.)reST";
762
763	static const char AttrDoc_ArmOut[] = R"reST(The ``__arm_out`` keyword applies to prototyped function types and specifies
764	that the function shares a given state S with its caller. For ``__arm_out``,
765	the function ignores the incoming state for S and returns new state for S.
766
767	The attribute takes string arguments to instruct the compiler which state
768	is shared. The supported states for S are:
769
770	* ``"za"`` for Matrix Storage (requires SME)
771
772	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
773	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
774
775	static const char AttrDoc_ArmPreserves[] = R"reST(The ``__arm_preserves`` keyword applies to prototyped function types and
776	specifies that the function does not read a given state S and returns
777	with state S unchanged.
778
779	The attribute takes string arguments to instruct the compiler which state
780	is shared. The supported states for S are:
781
782	* ``"za"`` for Matrix Storage (requires SME)
783
784	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
785	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
786
787	static const char AttrDoc_ArmStreaming[] = R"reST(The ``__arm_streaming`` keyword applies to prototyped function types and specifies
788	that the function has a "streaming interface". This means that:
789
790	* the function requires that the processor implements the Scalable Matrix
791	Extension (SME).
792
793	* the function must be entered in streaming mode (that is, with PSTATE.SM
794	set to 1)
795
796	* the function must return in streaming mode
797
798	Clang manages PSTATE.SM automatically; it is not the source code's
799	responsibility to do this. For example, if a non-streaming
800	function calls an ``__arm_streaming`` function, Clang generates code
801	that switches into streaming mode before calling the function and
802	switches back to non-streaming mode on return.)reST";
803
804	static const char AttrDoc_ArmStreamingCompatible[] = R"reST(The ``__arm_streaming_compatible`` keyword applies to prototyped function types and
805	specifies that the function has a "streaming compatible interface". This
806	means that:
807
808	* the function may be entered in either non-streaming mode (PSTATE.SM=0) or
809	in streaming mode (PSTATE.SM=1).
810
811	* the function must return in the same mode as it was entered.
812
813	* the code executed in the function is compatible with either mode.
814
815	Clang manages PSTATE.SM automatically; it is not the source code's
816	responsibility to do this. Clang will ensure that the generated code in
817	streaming-compatible functions is valid in either mode (PSTATE.SM=0 or
818	PSTATE.SM=1). For example, if an ``__arm_streaming_compatible`` function calls a
819	non-streaming function, Clang generates code to temporarily switch out of streaming
820	mode before calling the function and switch back to streaming-mode on return if
821	``PSTATE.SM`` is ``1`` on entry of the caller. If ``PSTATE.SM`` is ``0`` on
822	entry to the ``__arm_streaming_compatible`` function, the call will be executed
823	without changing modes.)reST";
824
825	static const char AttrDoc_Artificial[] = R"reST(The ``artificial`` attribute can be applied to an inline function. If such a
826	function is inlined, the attribute indicates that debuggers should associate
827	the resulting instructions with the call site, rather than with the
828	corresponding line within the inlined callee.)reST";
829
830	static const char AttrDoc_AsmLabel[] = R"reST(This attribute can be used on a function or variable to specify its symbol name.
831
832	On some targets, all C symbols are prefixed by default with a single character,
833	typically ``_``. This was done historically to distinguish them from symbols
834	used by other languages. (This prefix is also added to the standard Itanium
835	C++ ABI prefix on "mangled" symbol names, so that e.g. on such targets the true
836	symbol name for a C++ variable declared as ``int cppvar;`` would be
837	``__Z6cppvar``; note the two underscores.) This prefix is not added to the
838	symbol names specified by the ``__asm`` attribute; programmers wishing to match
839	a C symbol name must compensate for this.
840
841	For example, consider the following C code:
842
843	.. code-block:: c
844
845	int var1 __asm("altvar") = 1; // "altvar" in symbol table.
846	int var2 = 1; // "_var2" in symbol table.
847
848	void func1(void) __asm("altfunc");
849	void func1(void) {} // "altfunc" in symbol table.
850	void func2(void) {} // "_func2" in symbol table.
851
852	Clang's implementation of this attribute is compatible with GCC's, `documented here <https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html>`_.
853
854	While it is possible to use this attribute to name a special symbol used
855	internally by the compiler, such as an LLVM intrinsic, this is neither
856	recommended nor supported and may cause the compiler to crash or miscompile.
857	Users who wish to gain access to intrinsic behavior are strongly encouraged to
858	request new builtin functions.)reST";
859
860	static const char AttrDoc_AssertCapability[] = R"reST(Marks a function that dynamically tests whether a capability is held, and halts
861	the program if it is not held.)reST";
862
863	static const char AttrDoc_AssumeAligned[] = R"reST(Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function
864	declaration to specify that the return value of the function (which must be a
865	pointer type) has the specified offset, in bytes, from an address with the
866	specified alignment. The offset is taken to be zero if omitted.
867
868	.. code-block:: c++
869
870	// The returned pointer value has 32-byte alignment.
871	void *a() __attribute__((assume_aligned (32)));
872
873	// The returned pointer value is 4 bytes greater than an address having
874	// 32-byte alignment.
875	void *b() __attribute__((assume_aligned (32, 4)));
876
877	Note that this attribute provides information to the compiler regarding a
878	condition that the code already ensures is true. It does not cause the compiler
879	to enforce the provided alignment assumption.)reST";
880
881	static const char AttrDoc_Atomic[] = R"reST(The ``atomic`` attribute can be applied to compound statements to override or
882	further specify the default atomic code-generation behavior, especially on
883	targets such as AMDGPU. You can annotate compound statements with options
884	to modify how atomic instructions inside that statement are emitted at the IR
885	level.
886
887	For details, see the documentation for `@atomic
888	<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-controlling-atomic-code-generation>`_)reST";
889
890	static const char AttrDoc_Availability[] = R"reST(The ``availability`` attribute can be placed on declarations to describe the
891	lifecycle of that declaration relative to operating system versions. Consider
892	the function declaration for a hypothetical function ``f``:
893
894	.. code-block:: c++
895
896	void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
897
898	The availability attribute states that ``f`` was introduced in macOS 10.4,
899	deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
900	is used by Clang to determine when it is safe to use ``f``: for example, if
901	Clang is instructed to compile code for macOS 10.5, a call to ``f()``
902	succeeds. If Clang is instructed to compile code for macOS 10.6, the call
903	succeeds but Clang emits a warning specifying that the function is deprecated.
904	Finally, if Clang is instructed to compile code for macOS 10.7, the call
905	fails because ``f()`` is no longer available.
906
907	Clang is instructed to compile code for a minimum deployment version using
908	the ``-target`` or ``-mtargetos`` command line arguments. For example,
909	macOS 10.7 would be specified as ``-target x86_64-apple-macos10.7`` or
910	``-mtargetos=macos10.7``. Variants like Mac Catalyst are specified as
911	``-target arm64-apple-ios15.0-macabi`` or ``-mtargetos=ios15.0-macabi``
912
913	The availability attribute is a comma-separated list starting with the
914	platform name and then including clauses specifying important milestones in the
915	declaration's lifetime (in any order) along with additional information. Those
916	clauses can be:
917
918	introduced=\ version
919	The first version in which this declaration was introduced.
920
921	deprecated=\ version
922	The first version in which this declaration was deprecated, meaning that
923	users should migrate away from this API.
924
925	obsoleted=\ version
926	The first version in which this declaration was obsoleted, meaning that it
927	was removed completely and can no longer be used.
928
929	unavailable
930	This declaration is never available on this platform.
931
932	message=\ string-literal
933	Additional message text that Clang will provide when emitting a warning or
934	error about use of a deprecated or obsoleted declaration. Useful to direct
935	users to replacement APIs.
936
937	replacement=\ string-literal
938	Additional message text that Clang will use to provide Fix-It when emitting
939	a warning about use of a deprecated declaration. The Fix-It will replace
940	the deprecated declaration with the new declaration specified.
941
942	environment=\ identifier
943	Target environment in which this declaration is available. If present,
944	the availability attribute applies only to targets with the same platform
945	and environment. The parameter is currently supported only in HLSL.
946
947	Multiple availability attributes can be placed on a declaration, which may
948	correspond to different platforms. For most platforms, the availability
949	attribute with the platform corresponding to the target platform will be used;
950	any others will be ignored. However, the availability for ``watchOS`` and
951	``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute.
952	Any explicit availability attributes for those platforms are still preferred over
953	the implicitly inferred availability attributes. If no availability attribute
954	specifies availability for the current target platform, the availability
955	attributes are ignored. Supported platforms are:
956
957	``iOS``
958	``macOS``
959	``tvOS``
960	``watchOS``
961	``iOSApplicationExtension``
962	``macOSApplicationExtension``
963	``tvOSApplicationExtension``
964	``watchOSApplicationExtension``
965	``macCatalyst``
966	``macCatalystApplicationExtension``
967	``visionOS``
968	``visionOSApplicationExtension``
969	``driverkit``
970	``swift``
971	``android``
972	``fuchsia``
973	``ohos``
974	``zos``
975	``ShaderModel``
976
977	Some platforms have alias names:
978
979	``ios``
980	``macos``
981	``macosx (deprecated)``
982	``tvos``
983	``watchos``
984	``ios_app_extension``
985	``macos_app_extension``
986	``macosx_app_extension (deprecated)``
987	``tvos_app_extension``
988	``watchos_app_extension``
989	``maccatalyst``
990	``maccatalyst_app_extension``
991	``visionos``
992	``visionos_app_extension``
993	``shadermodel``
994
995	Supported environment names for the ShaderModel platform:
996
997	``pixel``
998	``vertex``
999	``geometry``
1000	``hull``
1001	``domain``
1002	``compute``
1003	``raygeneration``
1004	``intersection``
1005	``anyhit``
1006	``closesthit``
1007	``miss``
1008	``callable``
1009	``mesh``
1010	``amplification``
1011	``library``
1012
1013	A declaration can typically be used even when deploying back to a platform
1014	version prior to when the declaration was introduced. When this happens, the
1015	declaration is `weakly linked
1016	<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
1017	as if the ``weak_import`` attribute were added to the declaration. A
1018	weakly-linked declaration may or may not be present a run-time, and a program
1019	can determine whether the declaration is present by checking whether the
1020	address of that declaration is non-NULL.
1021
1022	The flag ``strict`` disallows using API when deploying back to a
1023	platform version prior to when the declaration was introduced. An
1024	attempt to use such API before its introduction causes a hard error.
1025	Weakly-linking is almost always a better API choice, since it allows
1026	users to query availability at runtime.
1027
1028	If there are multiple declarations of the same entity, the availability
1029	attributes must either match on a per-platform basis or later
1030	declarations must not have availability attributes for that
1031	platform. For example:
1032
1033	.. code-block:: c
1034
1035	void g(void) __attribute__((availability(macos,introduced=10.4)));
1036	void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
1037	void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
1038	void g(void); // okay, inherits both macos and ios availability from above.
1039	void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
1040
1041	When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
1042
1043	.. code-block:: objc
1044
1045	@interface A
1046	- (id)method __attribute__((availability(macos,introduced=10.4)));
1047	- (id)method2 __attribute__((availability(macos,introduced=10.4)));
1048	@end
1049
1050	@interface B : A
1051	- (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
1052	- (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
1053	@end
1054
1055	Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
1056	``<os/availability.h>`` can simplify the spelling:
1057
1058	.. code-block:: objc
1059
1060	@interface A
1061	- (id)method API_AVAILABLE(macos(10.11)));
1062	- (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
1063	@end
1064
1065	Availability attributes can also be applied using a ``#pragma clang attribute``.
1066	Any explicit availability attribute whose platform corresponds to the target
1067	platform is applied to a declaration regardless of the availability attributes
1068	specified in the pragma. For example, in the code below,
1069	``hasExplicitAvailabilityAttribute`` will use the ``macOS`` availability
1070	attribute that is specified with the declaration, whereas
1071	``getsThePragmaAvailabilityAttribute`` will use the ``macOS`` availability
1072	attribute that is applied by the pragma.
1073
1074	.. code-block:: c
1075
1076	#pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)
1077	void getsThePragmaAvailabilityAttribute(void);
1078	void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4)));
1079	#pragma clang attribute pop
1080
1081	For platforms like ``watchOS`` and ``tvOS``, whose availability attributes can
1082	be implicitly inferred from an ``iOS`` availability attribute, the logic is
1083	slightly more complex. The explicit and the pragma-applied availability
1084	attributes whose platform corresponds to the target platform are applied as
1085	described in the previous paragraph. However, the implicitly inferred attributes
1086	are applied to a declaration only when there is no explicit or pragma-applied
1087	availability attribute whose platform corresponds to the target platform. For
1088	example, the function below will receive the ``tvOS`` availability from the
1089	pragma rather than using the inferred ``iOS`` availability from the declaration:
1090
1091	.. code-block:: c
1092
1093	#pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)
1094	void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0)));
1095	#pragma clang attribute pop
1096
1097	The compiler is also able to apply implicitly inferred attributes from a pragma
1098	as well. For example, when targeting ``tvOS``, the function below will receive
1099	a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS``
1100	availability attribute applied by the pragma:
1101
1102	.. code-block:: c
1103
1104	#pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)
1105	void infersTVOSAvailabilityFromPragma(void);
1106	#pragma clang attribute pop
1107
1108	The implicit attributes that are inferred from explicitly specified attributes
1109	whose platform corresponds to the target platform are applied to the declaration
1110	even if there is an availability attribute that can be inferred from a pragma.
1111	For example, the function below will receive the ``tvOS, introduced=11.0``
1112	availability that is inferred from the attribute on the declaration rather than
1113	inferring availability from the pragma:
1114
1115	.. code-block:: c
1116
1117	#pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)
1118	void infersTVOSAvailabilityFromAttributeNextToDeclaration(void)
1119	__attribute__((availability(iOS,introduced=11.0)));
1120	#pragma clang attribute pop
1121
1122	Also see the documentation for `@available
1123	<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_)reST";
1124
1125	static const char AttrDoc_AvailableOnlyInDefaultEvalMethod[] = R"reST(No documentation.)reST";
1126
1127	static const char AttrDoc_BPFFastCall[] = R"reST(Functions annotated with this attribute are likely to be inlined by BPF JIT.
1128	It is assumed that inlined implementation uses less caller saved registers,
1129	than a regular function.
1130	Specifically, the following registers are likely to be preserved:
1131	- ``R0`` if function return value is ``void``;
1132	- ``R2-R5` if function takes 1 argument;
1133	- ``R3-R5` if function takes 2 arguments;
1134	- ``R4-R5` if function takes 3 arguments;
1135	- ``R5`` if function takes 4 arguments;
1136
1137	For such functions Clang generates code pattern that allows BPF JIT
1138	to recognize and remove unnecessary spills and fills of the preserved
1139	registers.)reST";
1140
1141	static const char AttrDoc_BPFPreserveAccessIndex[] = R"reST(Clang supports the ``__attribute__((preserve_access_index))``
1142	attribute for the BPF target. This attribute may be attached to a
1143	struct or union declaration, where if -g is specified, it enables
1144	preserving struct or union member access debuginfo indices of this
1145	struct or union, similar to clang ``__builtin_preserve_access_index()``.)reST";
1146
1147	static const char AttrDoc_BPFPreserveStaticOffset[] = R"reST(Clang supports the ``__attribute__((preserve_static_offset))``
1148	attribute for the BPF target. This attribute may be attached to a
1149	struct or union declaration. Reading or writing fields of types having
1150	such annotation is guaranteed to generate LDX/ST/STX instruction with
1151	offset corresponding to the field.
1152
1153	For example:
1154
1155	.. code-block:: c
1156
1157	struct foo {
1158	int a;
1159	int b;
1160	};
1161
1162	struct bar {
1163	int a;
1164	struct foo b;
1165	} __attribute__((preserve_static_offset));
1166
1167	void buz(struct bar *g) {
1168	g->b.a = 42;
1169	}
1170
1171	The assignment to ``g``'s field would produce an ST instruction with
1172	offset 8: ``*(u32)(r1 + 8) = 42;``.
1173
1174	Without this attribute generated instructions might be different,
1175	depending on optimizations behavior. E.g. the example above could be
1176	rewritten as ``r1 += 8; *(u32)(r1 + 0) = 42;``.)reST";
1177
1178	static const char AttrDoc_BTFDeclTag[] = R"reST(Clang supports the ``__attribute__((btf_decl_tag("ARGUMENT")))`` attribute for
1179	all targets. This attribute may be attached to a struct/union, struct/union
1180	field, function, function parameter, variable or typedef declaration. If -g is
1181	specified, the ``ARGUMENT`` info will be preserved in IR and be emitted to
1182	dwarf. For BPF targets, the ``ARGUMENT`` info will be emitted to .BTF ELF
1183	section too.)reST";
1184
1185	static const char AttrDoc_BTFTypeTag[] = R"reST(Clang supports the ``__attribute__((btf_type_tag("ARGUMENT")))`` attribute for
1186	all targets. It only has effect when ``-g`` is specified on the command line and
1187	is currently silently ignored when not applied to a pointer type (note: this
1188	scenario may be diagnosed in the future).
1189
1190	The ``ARGUMENT`` string will be preserved in IR and emitted to DWARF for the
1191	types used in variable declarations, function declarations, or typedef
1192	declarations.
1193
1194	For BPF targets, the ``ARGUMENT`` string will also be emitted to .BTF ELF
1195	section.)reST";
1196
1197	static const char AttrDoc_Blocking[] = R"reST(Declares that a function potentially blocks, and prevents any potential inference of ``nonblocking``
1198	by the compiler.)reST";
1199
1200	static const char AttrDoc_Blocks[] = R"reST(No documentation.)reST";
1201
1202	static const char AttrDoc_Builtin[] = R"reST()reST";
1203
1204	static const char AttrDoc_BuiltinAlias[] = R"reST(This attribute is used in the implementation of the C intrinsics.
1205	It allows the C intrinsic functions to be declared using the names defined
1206	in target builtins, and still be recognized as clang builtins equivalent to the
1207	underlying name. For example, ``riscv_vector.h`` declares the function ``vadd``
1208	with ``__attribute__((clang_builtin_alias(__builtin_rvv_vadd_vv_i8m1)))``.
1209	This ensures that both functions are recognized as that clang builtin,
1210	and in the latter case, the choice of which builtin to identify the
1211	function as can be deferred until after overload resolution.
1212
1213	This attribute can only be used to set up the aliases for certain ARM/RISC-V
1214	C intrinsic functions; it is intended for use only inside ``arm_*.h`` and
1215	``riscv_*.h`` and is not a general mechanism for declaring arbitrary aliases
1216	for clang builtin functions.)reST";
1217
1218	static const char AttrDoc_C11NoReturn[] = R"reST(A function declared as ``_Noreturn`` shall not return to its caller. The
1219	compiler will generate a diagnostic for a function declared as ``_Noreturn``
1220	that appears to be capable of returning to its caller. Despite being a type
1221	specifier, the ``_Noreturn`` attribute cannot be specified on a function
1222	pointer type.)reST";
1223
1224	static const char AttrDoc_CDecl[] = R"reST(No documentation.)reST";
1225
1226	static const char AttrDoc_CFAuditedTransfer[] = R"reST(No documentation.)reST";
1227
1228	static const char AttrDoc_CFConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1229	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1230	convention (e.g. functions starting with "get" are assumed to return at
1231	``+0``).
1232
1233	It can be overridden using a family of the following attributes. In
1234	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1235	a function communicates that the object is returned at ``+1``, and the caller
1236	is responsible for freeing it.
1237	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1238	specifies that the object is returned at ``+0`` and the ownership remains with
1239	the callee.
1240	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1241	the Objective-C method call consumes the reference to ``self``, e.g. by
1242	attaching it to a supplied parameter.
1243	Additionally, parameters can have an annotation
1244	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1245	as that parameter effectively transfers the ownership, and the caller is no
1246	longer responsible for it.
1247	These attributes affect code generation when interacting with ARC code, and
1248	they are used by the Clang Static Analyzer.
1249
1250	In C programs using CoreFoundation, a similar set of attributes:
1251	``__attribute__((cf_returns_not_retained))``,
1252	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1253	have the same respective semantics when applied to CoreFoundation objects.
1254	These attributes affect code generation when interacting with ARC code, and
1255	they are used by the Clang Static Analyzer.
1256
1257	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1258	the same attribute family is present:
1259	``__attribute__((os_returns_not_retained))``,
1260	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1261	with the same respective semantics.
1262	Similar to ``__attribute__((ns_consumes_self))``,
1263	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1264	the reference to "this" (e.g., when attaching it to a different object supplied
1265	as a parameter).
1266	Out parameters (parameters the function is meant to write into,
1267	either via pointers-to-pointers or references-to-pointers)
1268	may be annotated with ``__attribute__((os_returns_retained))``
1269	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1270	written into the out parameter should (or respectively should not) be released
1271	after use.
1272	Since often out parameters may or may not be written depending on the exit
1273	code of the function,
1274	annotations ``__attribute__((os_returns_retained_on_zero))``
1275	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1276	an out parameter at ``+1`` is written if and only if the function returns a zero
1277	(respectively non-zero) error code.
1278	Observe that return-code-dependent out parameter annotations are only
1279	available for retained out parameters, as non-retained object do not have to be
1280	released by the callee.
1281	These attributes are only used by the Clang Static Analyzer.
1282
1283	The family of attributes ``X_returns_X_retained`` can be added to functions,
1284	C++ methods, and Objective-C methods and properties.
1285	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1286	and Objective-C methods.)reST";
1287
1288	static const char AttrDoc_CFGuard[] = R"reST(Code can indicate CFG checks are not wanted with the ``__declspec(guard(nocf))``
1289	attribute. This directs the compiler to not insert any CFG checks for the entire
1290	function. This approach is typically used only sparingly in specific situations
1291	where the programmer has manually inserted "CFG-equivalent" protection. The
1292	programmer knows that they are calling through some read-only function table
1293	whose address is obtained through read-only memory references and for which the
1294	index is masked to the function table limit. This approach may also be applied
1295	to small wrapper functions that are not inlined and that do nothing more than
1296	make a call through a function pointer. Since incorrect usage of this directive
1297	can compromise the security of CFG, the programmer must be very careful using
1298	the directive. Typically, this usage is limited to very small functions that
1299	only call one function.
1300
1301	`Control Flow Guard documentation <https://docs.microsoft.com/en-us/windows/win32/secbp/pe-metadata>`)reST";
1302
1303	static const char AttrDoc_CFICanonicalJumpTable[] = R"reST(Use ``__attribute__((cfi_canonical_jump_table))`` on a function declaration to
1304	make the function's CFI jump table canonical. See :ref:`the CFI documentation
1305	<cfi-canonical-jump-tables>` for more details.)reST";
1306
1307	static const char AttrDoc_CFISalt[] = R"reST(The ``cfi_salt`` attribute specifies a string literal that is used as a salt
1308	for Control-Flow Integrity (CFI) checks to distinguish between functions with
1309	the same type signature. This attribute can be applied to function declarations,
1310	function definitions, and function pointer typedefs.
1311
1312	The attribute prevents function pointers from being replaced with pointers to
1313	functions that have a compatible type, which can be a CFI bypass vector.
1314
1315	Syntax:
1316
1317	* GNU-style: ``__attribute__((cfi_salt("<salt_string>")))``
1318	* C++11-style: ``[[clang::cfi_salt("<salt_string>")]]``
1319
1320	Usage:
1321
1322	The attribute takes a single string literal argument that serves as the salt.
1323	Functions or function types with different salt values will have different CFI
1324	hashes, even if they have identical type signatures.
1325
1326	Motivation:
1327
1328	In large codebases like the Linux kernel, there are often hundreds of functions
1329	with identical type signatures that are called indirectly:
1330
1331	.. code-block::
1332
1333	1662 functions with void (*)(void)
1334	1179 functions with int (*)(void)
1335	...
1336
1337	By salting the CFI hashes, you can make CFI more robust by ensuring that
1338	functions intended for different purposes have distinct CFI identities.
1339
1340	Type Compatibility:
1341
1342	* Functions with different salt values are considered to have incompatible types
1343	* Function pointers with different salt values cannot be assigned to each other
1344	* All declarations of the same function must use the same salt value
1345
1346	Example:
1347
1348	.. code-block:: c
1349
1350	// Header file - define convenience macros
1351	#define __cfi_salt(s) __attribute__((cfi_salt(s)))
1352
1353	// Typedef for regular function pointers
1354	typedef int (*fptr_t)(void);
1355
1356	// Typedef for salted function pointers
1357	typedef int (*fptr_salted_t)(void) __cfi_salt("pepper");
1358
1359	struct widget_ops {
1360	fptr_t init; // Regular CFI
1361	fptr_salted_t exec; // Salted CFI
1362	fptr_t cleanup; // Regular CFI
1363	};
1364
1365	// Function implementations
1366	static int widget_init(void) { return 0; }
1367	static int widget_exec(void) __cfi_salt("pepper") { return 1; }
1368	static int widget_cleanup(void) { return 0; }
1369
1370	static struct widget_ops ops = {
1371	.init = widget_init, // OK - compatible types
1372	.exec = widget_exec, // OK - both use "pepper" salt
1373	.cleanup = widget_cleanup // OK - compatible types
1374	};
1375
1376	// Using C++11 attribute syntax
1377	void secure_callback(void) [[clang::cfi_salt("secure")]];
1378
1379	// This would cause a compilation error:
1380	// fptr_t bad_ptr = widget_exec; // Error: incompatible types
1381
1382	Notes:
1383
1384	* The salt string can contain non-NULL ASCII characters, including spaces and
1385	quotes
1386	* This attribute only applies to function types; using it on non-function
1387	types will generate a warning
1388	* All declarations and definitions of the same function must use identical
1389	salt values
1390	* The attribute affects type compatibility during compilation and CFI hash
1391	generation during code generation)reST";
1392
1393	static const char AttrDoc_CFIUncheckedCallee[] = R"reST(``cfi_unchecked_callee`` is a function type attribute which prevents the compiler from instrumenting
1394	`Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_ checks on indirect
1395	function calls. This also includes control flow checks added by
1396	`-fsanitize=function <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html#available-checks>`.
1397	Specifically, the attribute has the following semantics:
1398
1399	1. Indirect calls to a function type with this attribute will not be instrumented with CFI. That is,
1400	the indirect call will not be checked. Note that this only changes the behavior for indirect calls
1401	on pointers to function types having this attribute. It does not prevent all indirect function calls
1402	for a given type from being checked.
1403	2. All direct references to a function whose type has this attribute will always reference the
1404	function definition rather than an entry in the CFI jump table.
1405	3. When a pointer to a function with this attribute is implicitly cast to a pointer to a function
1406	without this attribute, the compiler will give a warning saying this attribute is discarded. This
1407	warning can be silenced with an explicit cast. Note an explicit cast just disables the warning, so
1408	direct references to a function with a ``cfi_unchecked_callee`` attribute will still reference the
1409	function definition rather than the CFI jump table.
1410
1411	.. code-block:: c
1412
1413	#define CFI_UNCHECKED_CALLEE __attribute__((cfi_unchecked_callee))
1414
1415	void no_cfi() CFI_UNCHECKED_CALLEE {}
1416
1417	void (*with_cfi)() = no_cfi; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
1418	// `with_cfi` also points to the actual definition of `no_cfi` rather than
1419	// its jump table entry.
1420
1421	void invoke(void (CFI_UNCHECKED_CALLEE *func)()) {
1422	func(); // CFI will not instrument this indirect call.
1423
1424	void (*func2)() = func; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
1425
1426	func2(); // CFI will instrument this indirect call. Users should be careful however because if this
1427	// references a function with type `cfi_unchecked_callee`, then the CFI check may incorrectly
1428	// fail because the reference will be to the function definition rather than the CFI jump
1429	// table entry.
1430	}
1431
1432	This attribute can only be applied on functions or member functions. This attribute can be a good
1433	alternative to ``no_sanitize("cfi")`` if you only want to disable innstrumentation for specific indirect
1434	calls rather than applying ``no_sanitize("cfi")`` on the whole function containing indirect call. Note
1435	that ``cfi_unchecked_attribute`` is a type attribute doesn't disable CFI instrumentation on a function
1436	body.)reST";
1437
1438	static const char AttrDoc_CFReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1439	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1440	convention (e.g. functions starting with "get" are assumed to return at
1441	``+0``).
1442
1443	It can be overridden using a family of the following attributes. In
1444	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1445	a function communicates that the object is returned at ``+1``, and the caller
1446	is responsible for freeing it.
1447	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1448	specifies that the object is returned at ``+0`` and the ownership remains with
1449	the callee.
1450	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1451	the Objective-C method call consumes the reference to ``self``, e.g. by
1452	attaching it to a supplied parameter.
1453	Additionally, parameters can have an annotation
1454	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1455	as that parameter effectively transfers the ownership, and the caller is no
1456	longer responsible for it.
1457	These attributes affect code generation when interacting with ARC code, and
1458	they are used by the Clang Static Analyzer.
1459
1460	In C programs using CoreFoundation, a similar set of attributes:
1461	``__attribute__((cf_returns_not_retained))``,
1462	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1463	have the same respective semantics when applied to CoreFoundation objects.
1464	These attributes affect code generation when interacting with ARC code, and
1465	they are used by the Clang Static Analyzer.
1466
1467	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1468	the same attribute family is present:
1469	``__attribute__((os_returns_not_retained))``,
1470	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1471	with the same respective semantics.
1472	Similar to ``__attribute__((ns_consumes_self))``,
1473	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1474	the reference to "this" (e.g., when attaching it to a different object supplied
1475	as a parameter).
1476	Out parameters (parameters the function is meant to write into,
1477	either via pointers-to-pointers or references-to-pointers)
1478	may be annotated with ``__attribute__((os_returns_retained))``
1479	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1480	written into the out parameter should (or respectively should not) be released
1481	after use.
1482	Since often out parameters may or may not be written depending on the exit
1483	code of the function,
1484	annotations ``__attribute__((os_returns_retained_on_zero))``
1485	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1486	an out parameter at ``+1`` is written if and only if the function returns a zero
1487	(respectively non-zero) error code.
1488	Observe that return-code-dependent out parameter annotations are only
1489	available for retained out parameters, as non-retained object do not have to be
1490	released by the callee.
1491	These attributes are only used by the Clang Static Analyzer.
1492
1493	The family of attributes ``X_returns_X_retained`` can be added to functions,
1494	C++ methods, and Objective-C methods and properties.
1495	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1496	and Objective-C methods.)reST";
1497
1498	static const char AttrDoc_CFReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1499	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1500	convention (e.g. functions starting with "get" are assumed to return at
1501	``+0``).
1502
1503	It can be overridden using a family of the following attributes. In
1504	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1505	a function communicates that the object is returned at ``+1``, and the caller
1506	is responsible for freeing it.
1507	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1508	specifies that the object is returned at ``+0`` and the ownership remains with
1509	the callee.
1510	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1511	the Objective-C method call consumes the reference to ``self``, e.g. by
1512	attaching it to a supplied parameter.
1513	Additionally, parameters can have an annotation
1514	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1515	as that parameter effectively transfers the ownership, and the caller is no
1516	longer responsible for it.
1517	These attributes affect code generation when interacting with ARC code, and
1518	they are used by the Clang Static Analyzer.
1519
1520	In C programs using CoreFoundation, a similar set of attributes:
1521	``__attribute__((cf_returns_not_retained))``,
1522	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1523	have the same respective semantics when applied to CoreFoundation objects.
1524	These attributes affect code generation when interacting with ARC code, and
1525	they are used by the Clang Static Analyzer.
1526
1527	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1528	the same attribute family is present:
1529	``__attribute__((os_returns_not_retained))``,
1530	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1531	with the same respective semantics.
1532	Similar to ``__attribute__((ns_consumes_self))``,
1533	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1534	the reference to "this" (e.g., when attaching it to a different object supplied
1535	as a parameter).
1536	Out parameters (parameters the function is meant to write into,
1537	either via pointers-to-pointers or references-to-pointers)
1538	may be annotated with ``__attribute__((os_returns_retained))``
1539	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1540	written into the out parameter should (or respectively should not) be released
1541	after use.
1542	Since often out parameters may or may not be written depending on the exit
1543	code of the function,
1544	annotations ``__attribute__((os_returns_retained_on_zero))``
1545	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1546	an out parameter at ``+1`` is written if and only if the function returns a zero
1547	(respectively non-zero) error code.
1548	Observe that return-code-dependent out parameter annotations are only
1549	available for retained out parameters, as non-retained object do not have to be
1550	released by the callee.
1551	These attributes are only used by the Clang Static Analyzer.
1552
1553	The family of attributes ``X_returns_X_retained`` can be added to functions,
1554	C++ methods, and Objective-C methods and properties.
1555	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1556	and Objective-C methods.)reST";
1557
1558	static const char AttrDoc_CFUnknownTransfer[] = R"reST(No documentation.)reST";
1559
1560	static const char AttrDoc_CPUDispatch[] = R"reST(The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
1561	resolve multiversioned functions. This form of multiversioning provides a
1562	mechanism for declaring versions across translation units and manually
1563	specifying the resolved function list. A specified CPU defines a set of minimum
1564	features that are required for the function to be called. The result of this is
1565	that future processors execute the most restrictive version of the function the
1566	new processor can execute.
1567
1568	In addition, unlike the ICC implementation of this feature, the selection of the
1569	version does not consider the manufacturer or microarchitecture of the processor.
1570	It tests solely the list of features that are both supported by the specified
1571	processor and present in the compiler-rt library. This can be surprising at times,
1572	as the runtime processor may be from a completely different manufacturer, as long
1573	as it supports the same feature set.
1574
1575	This can additionally be surprising, as some processors are indistringuishable from
1576	others based on the list of testable features. When this happens, the variant
1577	is selected in an unspecified manner.
1578
1579	Function versions are defined with ``cpu_specific``, which takes one or more CPU
1580	names as a parameter. For example:
1581
1582	.. code-block:: c
1583
1584	// Declares and defines the ivybridge version of single_cpu.
1585	__attribute__((cpu_specific(ivybridge)))
1586	void single_cpu(void){}
1587
1588	// Declares and defines the atom version of single_cpu.
1589	__attribute__((cpu_specific(atom)))
1590	void single_cpu(void){}
1591
1592	// Declares and defines both the ivybridge and atom version of multi_cpu.
1593	__attribute__((cpu_specific(ivybridge, atom)))
1594	void multi_cpu(void){}
1595
1596	A dispatching (or resolving) function can be declared anywhere in a project's
1597	source code with ``cpu_dispatch``. This attribute takes one or more CPU names
1598	as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
1599	are not expected to be defined, only declared. If such a marked function has a
1600	definition, any side effects of the function are ignored; trivial function
1601	bodies are permissible for ICC compatibility.
1602
1603	.. code-block:: c
1604
1605	// Creates a resolver for single_cpu above.
1606	__attribute__((cpu_dispatch(ivybridge, atom)))
1607	void single_cpu(void){}
1608
1609	// Creates a resolver for multi_cpu, but adds a 3rd version defined in another
1610	// translation unit.
1611	__attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
1612	void multi_cpu(void){}
1613
1614	Note that it is possible to have a resolving function that dispatches based on
1615	more or fewer options than are present in the program. Specifying fewer will
1616	result in the omitted options not being considered during resolution. Specifying
1617	a version for resolution that isn't defined in the program will result in a
1618	linking failure.
1619
1620	It is also possible to specify a CPU name of ``generic`` which will be resolved
1621	if the executing processor doesn't satisfy the features required in the CPU
1622	name. The behavior of a program executing on a processor that doesn't satisfy
1623	any option of a multiversioned function is undefined.)reST";
1624
1625	static const char AttrDoc_CPUSpecific[] = R"reST(The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
1626	resolve multiversioned functions. This form of multiversioning provides a
1627	mechanism for declaring versions across translation units and manually
1628	specifying the resolved function list. A specified CPU defines a set of minimum
1629	features that are required for the function to be called. The result of this is
1630	that future processors execute the most restrictive version of the function the
1631	new processor can execute.
1632
1633	In addition, unlike the ICC implementation of this feature, the selection of the
1634	version does not consider the manufacturer or microarchitecture of the processor.
1635	It tests solely the list of features that are both supported by the specified
1636	processor and present in the compiler-rt library. This can be surprising at times,
1637	as the runtime processor may be from a completely different manufacturer, as long
1638	as it supports the same feature set.
1639
1640	This can additionally be surprising, as some processors are indistringuishable from
1641	others based on the list of testable features. When this happens, the variant
1642	is selected in an unspecified manner.
1643
1644	Function versions are defined with ``cpu_specific``, which takes one or more CPU
1645	names as a parameter. For example:
1646
1647	.. code-block:: c
1648
1649	// Declares and defines the ivybridge version of single_cpu.
1650	__attribute__((cpu_specific(ivybridge)))
1651	void single_cpu(void){}
1652
1653	// Declares and defines the atom version of single_cpu.
1654	__attribute__((cpu_specific(atom)))
1655	void single_cpu(void){}
1656
1657	// Declares and defines both the ivybridge and atom version of multi_cpu.
1658	__attribute__((cpu_specific(ivybridge, atom)))
1659	void multi_cpu(void){}
1660
1661	A dispatching (or resolving) function can be declared anywhere in a project's
1662	source code with ``cpu_dispatch``. This attribute takes one or more CPU names
1663	as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
1664	are not expected to be defined, only declared. If such a marked function has a
1665	definition, any side effects of the function are ignored; trivial function
1666	bodies are permissible for ICC compatibility.
1667
1668	.. code-block:: c
1669
1670	// Creates a resolver for single_cpu above.
1671	__attribute__((cpu_dispatch(ivybridge, atom)))
1672	void single_cpu(void){}
1673
1674	// Creates a resolver for multi_cpu, but adds a 3rd version defined in another
1675	// translation unit.
1676	__attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
1677	void multi_cpu(void){}
1678
1679	Note that it is possible to have a resolving function that dispatches based on
1680	more or fewer options than are present in the program. Specifying fewer will
1681	result in the omitted options not being considered during resolution. Specifying
1682	a version for resolution that isn't defined in the program will result in a
1683	linking failure.
1684
1685	It is also possible to specify a CPU name of ``generic`` which will be resolved
1686	if the executing processor doesn't satisfy the features required in the CPU
1687	name. The behavior of a program executing on a processor that doesn't satisfy
1688	any option of a multiversioned function is undefined.)reST";
1689
1690	static const char AttrDoc_CUDAClusterDims[] = R"reST(In CUDA/HIP programming, the ``cluster_dims`` attribute, conventionally exposed as the
1691	``__cluster_dims__`` macro, can be applied to a kernel function to set the dimensions of a
1692	thread block cluster, which is an optional level of hierarchy and made up of thread blocks.
1693	``__cluster_dims__`` defines the cluster size as ``(X, Y, Z)``, where each value is the number
1694	of thread blocks in that dimension. The ``cluster_dims`` and `no_cluster`` attributes are
1695	mutually exclusive.
1696
1697	.. code::
1698
1699	__global__ __cluster_dims__(2, 1, 1) void kernel(...) {
1700	...
1701	})reST";
1702
1703	static const char AttrDoc_CUDAConstant[] = R"reST(No documentation.)reST";
1704
1705	static const char AttrDoc_CUDADevice[] = R"reST(No documentation.)reST";
1706
1707	static const char AttrDoc_CUDADeviceBuiltinSurfaceType[] = R"reST(The ``device_builtin_surface_type`` attribute can be applied to a class
1708	template when declaring the surface reference. A surface reference variable
1709	could be accessed on the host side and, on the device side, might be translated
1710	into an internal surface object, which is established through surface bind and
1711	unbind runtime APIs.)reST";
1712
1713	static const char AttrDoc_CUDADeviceBuiltinTextureType[] = R"reST(The ``device_builtin_texture_type`` attribute can be applied to a class
1714	template when declaring the texture reference. A texture reference variable
1715	could be accessed on the host side and, on the device side, might be translated
1716	into an internal texture object, which is established through texture bind and
1717	unbind runtime APIs.)reST";
1718
1719	static const char AttrDoc_CUDAGlobal[] = R"reST(No documentation.)reST";
1720
1721	static const char AttrDoc_CUDAGridConstant[] = R"reST(The ``__grid_constant__`` attribute can be applied to a ``const``-qualified kernel
1722	function argument and allows compiler to take the address of that argument without
1723	making a copy. The argument applies to sm_70 or newer GPUs, during compilation
1724	with CUDA-11.7(PTX 7.7) or newer, and is ignored otherwise.)reST";
1725
1726	static const char AttrDoc_CUDAHost[] = R"reST(No documentation.)reST";
1727
1728	static const char AttrDoc_CUDAInvalidTarget[] = R"reST()reST";
1729
1730	static const char AttrDoc_CUDALaunchBounds[] = R"reST(No documentation.)reST";
1731
1732	static const char AttrDoc_CUDANoCluster[] = R"reST(In CUDA/HIP programming, a kernel function can still be launched with the cluster feature enabled
1733	at runtime, even without being annotated with ``__cluster_dims__``. The LLVM/Clang-exclusive
1734	``no_cluster`` attribute, conventionally exposed as the ``__no_cluster__`` macro, can be applied to
1735	a kernel function to explicitly indicate that the cluster feature will not be enabled either at
1736	compile time or at kernel launch time. This allows the compiler to apply certain optimizations
1737	without assuming that clustering could be enabled at runtime. It is undefined behavior to launch a
1738	kernel annotated with ``__no_cluster__`` if the cluster feature is enabled at runtime.
1739	The ``cluster_dims`` and ``no_cluster`` attributes are mutually exclusive.
1740
1741	.. code::
1742
1743	__global__ __no_cluster__ void kernel(...) {
1744	...
1745	})reST";
1746
1747	static const char AttrDoc_CUDAShared[] = R"reST(No documentation.)reST";
1748
1749	static const char AttrDoc_CXX11NoReturn[] = R"reST(A function declared as ``[[noreturn]]`` shall not return to its caller. The
1750	compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
1751	that appears to be capable of returning to its caller.
1752
1753	The ``[[_Noreturn]]`` spelling is deprecated and only exists to ease code
1754	migration for code using ``[[noreturn]]`` after including ``<stdnoreturn.h>``.)reST";
1755
1756	static const char AttrDoc_CXXAssume[] = R"reST(The ``assume`` attribute is used to indicate to the optimizer that a
1757	certain condition is assumed to be true at a certain point in the
1758	program. If this condition is violated at runtime, the behavior is
1759	undefined. ``assume`` can only be applied to a null statement.
1760
1761	Different optimisers are likely to react differently to the presence of
1762	this attribute; in some cases, adding ``assume`` may affect performance
1763	negatively. It should be used with parsimony and care.
1764
1765	Example:
1766
1767	.. code-block:: c++
1768
1769	int f(int x, int y) {
1770	[[assume(x == 27)]];
1771	[[assume(x == y)]];
1772	return y + 1; // May be optimised to `return 28`.
1773	})reST";
1774
1775	static const char AttrDoc_CallableWhen[] = R"reST(Use ``__attribute__((callable_when(...)))`` to indicate what states a method
1776	may be called in. Valid states are unconsumed, consumed, or unknown. Each
1777	argument to this attribute must be a quoted string. E.g.:
1778
1779	``__attribute__((callable_when("unconsumed", "unknown")))``)reST";
1780
1781	static const char AttrDoc_Callback[] = R"reST(The ``callback`` attribute specifies that the annotated function may invoke the
1782	specified callback zero or more times. The callback, as well as the passed
1783	arguments, are identified by their parameter name or position (starting with
1784	1!) in the annotated function. The first position in the attribute identifies
1785	the callback callee, the following positions declare describe its arguments.
1786	The callback callee is required to be callable with the number, and order, of
1787	the specified arguments. The index ``0``, or the identifier ``this``, is used to
1788	represent an implicit "this" pointer in class methods. If there is no implicit
1789	"this" pointer it shall not be referenced. The index '-1', or the name "__",
1790	represents an unknown callback callee argument. This can be a value which is
1791	not present in the declared parameter list, or one that is, but is potentially
1792	inspected, captured, or modified. Parameter names and indices can be mixed in
1793	the callback attribute.
1794
1795	The ``callback`` attribute, which is directly translated to ``callback``
1796	metadata <http://llvm.org/docs/LangRef.html#callback-metadata>, make the
1797	connection between the call to the annotated function and the callback callee.
1798	This can enable interprocedural optimizations which were otherwise impossible.
1799	If a function parameter is mentioned in the ``callback`` attribute, through its
1800	position, it is undefined if that parameter is used for anything other than the
1801	actual callback. Inspected, captured, or modified parameters shall not be
1802	listed in the ``callback`` metadata.
1803
1804	Example encodings for the callback performed by ``pthread_create`` are shown
1805	below. The explicit attribute annotation indicates that the third parameter
1806	(``start_routine``) is called zero or more times by the ``pthread_create`` function,
1807	and that the fourth parameter (``arg``) is passed along. Note that the callback
1808	behavior of ``pthread_create`` is automatically recognized by Clang. In addition,
1809	the declarations of ``__kmpc_fork_teams`` and ``__kmpc_fork_call``, generated for
1810	``#pragma omp target teams`` and ``#pragma omp parallel``, respectively, are also
1811	automatically recognized as broker functions. Further functions might be added
1812	in the future.
1813
1814	.. code-block:: c
1815
1816	__attribute__((callback (start_routine, arg)))
1817	int pthread_create(pthread_t thread, const pthread_attr_t attr,
1818	void (start_routine) (void ), void arg);
1819
1820	__attribute__((callback (3, 4)))
1821	int pthread_create(pthread_t thread, const pthread_attr_t attr,
1822	void (start_routine) (void ), void arg);)reST";
1823
1824	static const char AttrDoc_CalledOnce[] = R"reST(The ``called_once`` attribute specifies that the annotated function or method
1825	parameter is invoked exactly once on all execution paths. It only applies
1826	to parameters with function-like types, i.e. function pointers or blocks. This
1827	concept is particularly useful for asynchronous programs.
1828
1829	Clang implements a check for ``called_once`` parameters,
1830	``-Wcalled-once-parameter``. It is on by default and finds the following
1831	violations:
1832
1833	* Parameter is not called at all.
1834
1835	* Parameter is called more than once.
1836
1837	* Parameter is not called on one of the execution paths.
1838
1839	In the latter case, Clang pinpoints the path where parameter is not invoked
1840	by showing the control-flow statement where the path diverges.
1841
1842	.. code-block:: objc
1843
1844	void fooWithCallback(void (^callback)(void) __attribute__((called_once))) {
1845	if (somePredicate()) {
1846	...
1847	callback();
1848	} else {
1849	callback(); // OK: callback is called on every path
1850	}
1851	}
1852
1853	void barWithCallback(void (^callback)(void) __attribute__((called_once))) {
1854	if (somePredicate()) {
1855	...
1856	callback(); // note: previous call is here
1857	}
1858	callback(); // warning: callback is called twice
1859	}
1860
1861	void foobarWithCallback(void (^callback)(void) __attribute__((called_once))) {
1862	if (somePredicate()) { // warning: callback is not called when condition is false
1863	...
1864	callback();
1865	}
1866	}
1867
1868	This attribute is useful for API developers who want to double-check if they
1869	implemented their method correctly.)reST";
1870
1871	static const char AttrDoc_Capability[] = R"reST(No documentation.)reST";
1872
1873	static const char AttrDoc_CapturedRecord[] = R"reST()reST";
1874
1875	static const char AttrDoc_CarriesDependency[] = R"reST(The ``carries_dependency`` attribute specifies dependency propagation into and
1876	out of functions.
1877
1878	When specified on a function or Objective-C method, the ``carries_dependency``
1879	attribute means that the return value carries a dependency out of the function,
1880	so that the implementation need not constrain ordering upon return from that
1881	function. Implementations of the function and its caller may choose to preserve
1882	dependencies instead of emitting memory ordering instructions such as fences.
1883
1884	Note, this attribute does not change the meaning of the program, but may result
1885	in generation of more efficient code.)reST";
1886
1887	static const char AttrDoc_Cleanup[] = R"reST(This attribute allows a function to be run when a local variable goes out of
1888	scope. The attribute takes the identifier of a function with a parameter type
1889	that is a pointer to the type with the attribute.
1890
1891	.. code-block:: c
1892
1893	static void foo (int *) { ... }
1894	static void bar (int *) { ... }
1895	void baz (void) {
1896	int x __attribute__((cleanup(foo)));
1897	{
1898	int y __attribute__((cleanup(bar)));
1899	}
1900	}
1901
1902	The above example will result in a call to ``bar`` being passed the address of
1903	``y`` when ``y`` goes out of scope, then a call to ``foo`` being passed the
1904	address of ``x`` when ``x`` goes out of scope. If two or more variables share
1905	the same scope, their ``cleanup`` callbacks are invoked in the reverse order
1906	the variables were declared in. It is not possible to check the return value
1907	(if any) of these ``cleanup`` callback functions.)reST";
1908
1909	static const char AttrDoc_ClspvLibclcBuiltin[] = R"reST(Attribute used by `clspv`_ (OpenCL-C to Vulkan SPIR-V compiler) to identify functions coming from `libclc`_ (OpenCL-C builtin library).
1910
1911	.. code-block:: c
1912
1913	void __attribute__((clspv_libclc_builtin)) libclc_builtin() {}
1914
1915	.. _`clspv`: https://github.com/google/clspv
1916	.. _`libclc`: https://libclc.llvm.org)reST";
1917
1918	static const char AttrDoc_CmseNSCall[] = R"reST(This attribute declares a non-secure function type. When compiling for secure
1919	state, a call to such a function would switch from secure to non-secure state.
1920	All non-secure function calls must happen only through a function pointer, and
1921	a non-secure function type should only be used as a base type of a pointer.
1922	See `ARMv8-M Security Extensions: Requirements on Development
1923	Tools - Engineering Specification Documentation
1924	<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.)reST";
1925
1926	static const char AttrDoc_CmseNSEntry[] = R"reST(This attribute declares a function that can be called from non-secure state, or
1927	from secure state. Entering from and returning to non-secure state would switch
1928	to and from secure state, respectively, and prevent flow of information
1929	to non-secure state, except via return values. See `ARMv8-M Security Extensions:
1930	Requirements on Development Tools - Engineering Specification Documentation
1931	<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.)reST";
1932
1933	static const char AttrDoc_CodeAlign[] = R"reST(The ``clang::code_align(N)`` attribute applies to a loop and specifies the byte
1934	alignment for a loop. The attribute accepts a positive integer constant
1935	initialization expression indicating the number of bytes for the minimum
1936	alignment boundary. Its value must be a power of 2, between 1 and 4096
1937	(inclusive).
1938
1939	.. code-block:: c++
1940
1941	void foo() {
1942	int var = 0;
1943	[[clang::code_align(16)]] for (int i = 0; i < 10; ++i) var++;
1944	}
1945
1946	void Array(int *array, size_t n) {
1947	[[clang::code_align(64)]] for (int i = 0; i < n; ++i) array[i] = 0;
1948	}
1949
1950	void count () {
1951	int a1[10], int i = 0;
1952	[[clang::code_align(32)]] while (i < 10) { a1[i] += 3; }
1953	}
1954
1955	void check() {
1956	int a = 10;
1957	[[clang::code_align(8)]] do {
1958	a = a + 1;
1959	} while (a < 20);
1960	}
1961
1962	template<int A>
1963	void func() {
1964	[[clang::code_align(A)]] for(;;) { }
1965	})reST";
1966
1967	static const char AttrDoc_CodeModel[] = R"reST(The ``model`` attribute allows overriding the translation unit's
1968	code model (specified by ``-mcmodel``) for a specific global variable.
1969
1970	On LoongArch, allowed values are "normal", "medium", "extreme".
1971
1972	On x86-64, allowed values are ``"small"`` and ``"large"``. ``"small"`` is
1973	roughly equivalent to ``-mcmodel=small``, meaning the global is considered
1974	"small" placed closer to the ``.text`` section relative to "large" globals, and
1975	to prefer using 32-bit relocations to access the global. ``"large"`` is roughly
1976	equivalent to ``-mcmodel=large``, meaning the global is considered "large" and
1977	placed further from the ``.text`` section relative to "small" globals, and
1978	64-bit relocations must be used to access the global.)reST";
1979
1980	static const char AttrDoc_CodeSeg[] = R"reST(The ``__declspec(code_seg)`` attribute enables the placement of code into separate
1981	named segments that can be paged or locked in memory individually. This attribute
1982	is used to control the placement of instantiated templates and compiler-generated
1983	code. See the documentation for `__declspec(code_seg)`_ on MSDN.
1984
1985	.. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx)reST";
1986
1987	static const char AttrDoc_Cold[] = R"reST(``__attribute__((cold))`` marks a function as cold, as a manual alternative to PGO hotness data.
1988	If PGO data is available, the profile count based hotness overrides the ``__attribute__((cold))`` annotation (unlike ``__attribute__((hot))``).)reST";
1989
1990	static const char AttrDoc_Common[] = R"reST(No documentation.)reST";
1991
1992	static const char AttrDoc_Const[] = R"reST(No documentation.)reST";
1993
1994	static const char AttrDoc_ConstInit[] = R"reST(This attribute specifies that the variable to which it is attached is intended
1995	to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
1996	according to the rules of [basic.start.static]. The variable is required to
1997	have static or thread storage duration. If the initialization of the variable
1998	is not a constant initializer an error will be produced. This attribute may
1999	only be used in C++; the ``constinit`` spelling is only accepted in C++20
2000	onwards.
2001
2002	Note that in C++03 strict constant expression checking is not done. Instead
2003	the attribute reports if Clang can emit the variable as a constant, even if it's
2004	not technically a 'constant initializer'. This behavior is non-portable.
2005
2006	Static storage duration variables with constant initializers avoid hard-to-find
2007	bugs caused by the indeterminate order of dynamic initialization. They can also
2008	be safely used during dynamic initialization across translation units.
2009
2010	This attribute acts as a compile time assertion that the requirements
2011	for constant initialization have been met. Since these requirements change
2012	between dialects and have subtle pitfalls it's important to fail fast instead
2013	of silently falling back on dynamic initialization.
2014
2015	The first use of the attribute on a variable must be part of, or precede, the
2016	initializing declaration of the variable. C++20 requires the ``constinit``
2017	spelling of the attribute to be present on the initializing declaration if it
2018	is used anywhere. The other spellings can be specified on a forward declaration
2019	and omitted on a later initializing declaration.
2020
2021	.. code-block:: c++
2022
2023	// -std=c++14
2024	#define SAFE_STATIC [[clang::require_constant_initialization]]
2025	struct T {
2026	constexpr T(int) {}
2027	~T(); // non-trivial
2028	};
2029	SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
2030	SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
2031	// copy initialization is not a constant expression on a non-literal type.)reST";
2032
2033	static const char AttrDoc_Constructor[] = R"reST(The ``constructor`` attribute causes the function to be called before entering
2034	``main()``, and the ``destructor`` attribute causes the function to be called
2035	after returning from ``main()`` or when the ``exit()`` function has been
2036	called. Note, ``quick_exit()``, ``_Exit()``, and ``abort()`` prevent a function
2037	marked ``destructor`` from being called.
2038
2039	The constructor or destructor function should not accept any arguments and its
2040	return type should be ``void``.
2041
2042	The attributes accept an optional argument used to specify the priority order
2043	in which to execute constructor and destructor functions. The priority is
2044	given as an integer constant expression between 101 and 65535 (inclusive).
2045	Priorities outside of that range are reserved for use by the implementation. A
2046	lower value indicates a higher priority of initialization. Note that only the
2047	relative ordering of values is important. For example:
2048
2049	.. code-block:: c++
2050
2051	__attribute__((constructor(200))) void foo(void);
2052	__attribute__((constructor(101))) void bar(void);
2053
2054	``bar()`` will be called before ``foo()``, and both will be called before
2055	``main()``. If no argument is given to the ``constructor`` or ``destructor``
2056	attribute, they default to the value ``65535``.)reST";
2057
2058	static const char AttrDoc_Consumable[] = R"reST(Each ``class`` that uses any of the typestate annotations must first be marked
2059	using the ``consumable`` attribute. Failure to do so will result in a warning.
2060
2061	This attribute accepts a single parameter that must be one of the following:
2062	``unknown``, ``consumed``, or ``unconsumed``.)reST";
2063
2064	static const char AttrDoc_ConsumableAutoCast[] = R"reST(No documentation.)reST";
2065
2066	static const char AttrDoc_ConsumableSetOnRead[] = R"reST(No documentation.)reST";
2067
2068	static const char AttrDoc_Convergent[] = R"reST(The ``convergent`` attribute can be placed on a function declaration. It is
2069	translated into the LLVM ``convergent`` attribute, which indicates that the call
2070	instructions of a function with this attribute cannot be made control-dependent
2071	on any additional values.
2072
2073	This attribute is different from ``noduplicate`` because it allows duplicating
2074	function calls if it can be proved that the duplicated function calls are
2075	not made control-dependent on any additional values, e.g., unrolling a loop
2076	executed by all work items.
2077
2078	Sample usage:
2079
2080	.. code-block:: c
2081
2082	void convfunc(void) __attribute__((convergent));
2083	// Setting it as a C++11 attribute is also valid in a C++ program.
2084	// void convfunc(void) [[clang::convergent]];)reST";
2085
2086	static const char AttrDoc_CoroAwaitElidable[] = R"reST(The ``[[clang::coro_await_elidable]]`` is a class attribute which can be
2087	applied to a coroutine return type. It provides a hint to the compiler to apply
2088	Heap Allocation Elision more aggressively.
2089
2090	When a coroutine function returns such a type, a direct call expression therein
2091	that returns a prvalue of a type attributed ``[[clang::coro_await_elidable]]``
2092	is said to be under a safe elide context if one of the following is true:
2093	- it is the immediate right-hand side operand to a co_await expression.
2094	- it is an argument to a ``[[clang::coro_await_elidable_argument]]`` parameter
2095	or parameter pack of another direct call expression under a safe elide context.
2096
2097	Do note that the safe elide context applies only to the call expression itself,
2098	and the context does not transitively include any of its subexpressions unless
2099	exceptional rules of ``[[clang::coro_await_elidable_argument]]`` apply.
2100
2101	The compiler performs heap allocation elision on call expressions under a safe
2102	elide context, if the callee is a coroutine.
2103
2104	Example:
2105
2106	.. code-block:: c++
2107
2108	class [[clang::coro_await_elidable]] Task { ... };
2109
2110	Task foo();
2111	Task bar() {
2112	co_await foo(); // foo()'s coroutine frame on this line is elidable
2113	auto t = foo(); // foo()'s coroutine frame on this line is NOT elidable
2114	co_await t;
2115	}
2116
2117	Such elision replaces the heap allocated activation frame of the callee coroutine
2118	with a local variable within the enclosing braces in the caller's stack frame.
2119	The local variable, like other variables in coroutines, may be collected into the
2120	coroutine frame, which may be allocated on the heap. The behavior is undefined
2121	if the caller coroutine is destroyed earlier than the callee coroutine.)reST";
2122
2123	static const char AttrDoc_CoroAwaitElidableArgument[] = R"reST(The ``[[clang::coro_await_elidable_argument]]`` is a function parameter attribute.
2124	It works in conjunction with ``[[clang::coro_await_elidable]]`` to propagate a
2125	safe elide context to a parameter or parameter pack if the function is called
2126	under a safe elide context.
2127
2128	This is sometimes necessary on utility functions used to compose or modify the
2129	behavior of a callee coroutine.
2130
2131	Example:
2132
2133	.. code-block:: c++
2134
2135	template <typename T>
2136	class [[clang::coro_await_elidable]] Task { ... };
2137
2138	template <typename... T>
2139	class [[clang::coro_await_elidable]] WhenAll { ... };
2140
2141	// `when_all` is a utility function that composes coroutines. It does not
2142	// need to be a coroutine to propagate.
2143	template <typename... T>
2144	WhenAll<T...> when_all([[clang::coro_await_elidable_argument]] Task<T> tasks...);
2145
2146	Task<int> foo();
2147	Task<int> bar();
2148	Task<void> example1() {
2149	// `when_all``, `foo``, and `bar` are all elide safe because `when_all` is
2150	// under a safe elide context and, thanks to the [[clang::coro_await_elidable_argument]]
2151	// attribute, such context is propagated to foo and bar.
2152	co_await when_all(foo(), bar());
2153	}
2154
2155	Task<void> example2() {
2156	// `when_all` and `bar` are elide safe. `foo` is not elide safe.
2157	auto f = foo();
2158	co_await when_all(f, bar());
2159	}
2160
2161
2162	Task<void> example3() {
2163	// None of the calls are elide safe.
2164	auto t = when_all(foo(), bar());
2165	co_await t;
2166	})reST";
2167
2168	static const char AttrDoc_CoroDisableLifetimeBound[] = R"reST(The ``[[clang::coro_lifetimebound]]`` is a class attribute which can be applied
2169	to a coroutine return type (`coro_return_type, coro_wrapper`_) (i.e.
2170	it should also be annotated with ``[[clang::coro_return_type]]``).
2171
2172	All parameters of a function are considered to be lifetime bound if the function returns a
2173	coroutine return type (CRT) annotated with ``[[clang::coro_lifetimebound]]``.
2174	This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the function
2175	with ``[[clang::coro_disable_lifetimebound]]`` function attribute .
2176	See documentation of `lifetimebound`_ for details about lifetime bound analysis.
2177
2178
2179	Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.
2180
2181	For example,
2182
2183	.. code-block:: c++
2184
2185	task<int> coro(const int& a) { co_return a + 1; }
2186	task<int> dangling_refs(int a) {
2187	// `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.
2188	auto foo = coro(1);
2189	// `coro` captures reference to local variable `a` which is destroyed after the return.
2190	return coro(a);
2191	}
2192
2193	Lifetime bound static analysis can be used to detect such instances when coroutines capture references
2194	which may die earlier than the coroutine frame itself. In the above example, if the CRT `task` is annotated with
2195	``[[clang::coro_lifetimebound]]``, then lifetime bound analysis would detect capturing reference to
2196	temporaries or return address of a local variable.
2197
2198	Both coroutines and coroutine wrappers are part of this analysis.
2199
2200	.. code-block:: c++
2201
2202	template <typename T> struct [[clang::coro_return_type, clang::coro_lifetimebound]] Task {
2203	using promise_type = some_promise_type;
2204	};
2205
2206	Task<int> coro(const int& a) { co_return a + 1; }
2207	[[clang::coro_wrapper]] Task<int> coro_wrapper(const int& a, const int& b) {
2208	return a > b ? coro(a) : coro(b);
2209	}
2210	Task<int> temporary_reference() {
2211	auto foo = coro(1); // warning: capturing reference to a temporary which would die after the expression.
2212
2213	int a = 1;
2214	auto bar = coro_wrapper(a, 0); // warning: `b` captures reference to a temporary.
2215
2216	co_return co_await coro(1); // fine.
2217	}
2218	[[clang::coro_wrapper]] Task<int> stack_reference(int a) {
2219	return coro(a); // warning: returning address of stack variable `a`.
2220	}
2221
2222	This analysis can be disabled for all calls to a particular function by annotating the function
2223	with function attribute ``[[clang::coro_disable_lifetimebound]]``.
2224	For example, this could be useful for coroutine wrappers which accept reference parameters
2225	but do not pass them to the underlying coroutine or pass them by value.
2226
2227	.. code-block:: c++
2228
2229	Task<int> coro(int a) { co_return a + 1; }
2230	[[clang::coro_wrapper, clang::coro_disable_lifetimebound]] Task<int> coro_wrapper(const int& a) {
2231	return coro(a + 1);
2232	}
2233	void use() {
2234	auto task = coro_wrapper(1); // use of temporary is fine as the argument is not lifetime bound.
2235	})reST";
2236
2237	static const char AttrDoc_CoroLifetimeBound[] = R"reST(The ``[[clang::coro_lifetimebound]]`` is a class attribute which can be applied
2238	to a coroutine return type (`coro_return_type, coro_wrapper`_) (i.e.
2239	it should also be annotated with ``[[clang::coro_return_type]]``).
2240
2241	All parameters of a function are considered to be lifetime bound if the function returns a
2242	coroutine return type (CRT) annotated with ``[[clang::coro_lifetimebound]]``.
2243	This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the function
2244	with ``[[clang::coro_disable_lifetimebound]]`` function attribute .
2245	See documentation of `lifetimebound`_ for details about lifetime bound analysis.
2246
2247
2248	Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.
2249
2250	For example,
2251
2252	.. code-block:: c++
2253
2254	task<int> coro(const int& a) { co_return a + 1; }
2255	task<int> dangling_refs(int a) {
2256	// `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.
2257	auto foo = coro(1);
2258	// `coro` captures reference to local variable `a` which is destroyed after the return.
2259	return coro(a);
2260	}
2261
2262	Lifetime bound static analysis can be used to detect such instances when coroutines capture references
2263	which may die earlier than the coroutine frame itself. In the above example, if the CRT `task` is annotated with
2264	``[[clang::coro_lifetimebound]]``, then lifetime bound analysis would detect capturing reference to
2265	temporaries or return address of a local variable.
2266
2267	Both coroutines and coroutine wrappers are part of this analysis.
2268
2269	.. code-block:: c++
2270
2271	template <typename T> struct [[clang::coro_return_type, clang::coro_lifetimebound]] Task {
2272	using promise_type = some_promise_type;
2273	};
2274
2275	Task<int> coro(const int& a) { co_return a + 1; }
2276	[[clang::coro_wrapper]] Task<int> coro_wrapper(const int& a, const int& b) {
2277	return a > b ? coro(a) : coro(b);
2278	}
2279	Task<int> temporary_reference() {
2280	auto foo = coro(1); // warning: capturing reference to a temporary which would die after the expression.
2281
2282	int a = 1;
2283	auto bar = coro_wrapper(a, 0); // warning: `b` captures reference to a temporary.
2284
2285	co_return co_await coro(1); // fine.
2286	}
2287	[[clang::coro_wrapper]] Task<int> stack_reference(int a) {
2288	return coro(a); // warning: returning address of stack variable `a`.
2289	}
2290
2291	This analysis can be disabled for all calls to a particular function by annotating the function
2292	with function attribute ``[[clang::coro_disable_lifetimebound]]``.
2293	For example, this could be useful for coroutine wrappers which accept reference parameters
2294	but do not pass them to the underlying coroutine or pass them by value.
2295
2296	.. code-block:: c++
2297
2298	Task<int> coro(int a) { co_return a + 1; }
2299	[[clang::coro_wrapper, clang::coro_disable_lifetimebound]] Task<int> coro_wrapper(const int& a) {
2300	return coro(a + 1);
2301	}
2302	void use() {
2303	auto task = coro_wrapper(1); // use of temporary is fine as the argument is not lifetime bound.
2304	})reST";
2305
2306	static const char AttrDoc_CoroOnlyDestroyWhenComplete[] = R"reST(The `coro_only_destroy_when_complete` attribute should be marked on a C++ class. The coroutines
2307	whose return type is marked with the attribute are assumed to be destroyed only after the coroutine has
2308	reached the final suspend point.
2309
2310	This is helpful for the optimizers to reduce the size of the destroy function for the coroutines.
2311
2312	For example,
2313
2314	.. code-block:: c++
2315
2316	A foo() {
2317	dtor d;
2318	co_await something();
2319	dtor d1;
2320	co_await something();
2321	dtor d2;
2322	co_return 43;
2323	}
2324
2325	The compiler may generate the following pseudocode:
2326
2327	.. code-block:: c++
2328
2329	void foo.destroy(foo.Frame *frame) {
2330	switch(frame->suspend_index()) {
2331	case 1:
2332	frame->d.~dtor();
2333	break;
2334	case 2:
2335	frame->d.~dtor();
2336	frame->d1.~dtor();
2337	break;
2338	case 3:
2339	frame->d.~dtor();
2340	frame->d1.~dtor();
2341	frame->d2.~dtor();
2342	break;
2343	default: // coroutine completed or haven't started
2344	break;
2345	}
2346
2347	frame->promise.~promise_type();
2348	delete frame;
2349	}
2350
2351	The `foo.destroy()` function's purpose is to release all of the resources
2352	initialized for the coroutine when it is destroyed in a suspended state.
2353	However, if the coroutine is only ever destroyed at the final suspend state,
2354	the rest of the conditions are superfluous.
2355
2356	The user can use the `coro_only_destroy_when_complete` attributo suppress
2357	generation of the other destruction cases, optimizing the above `foo.destroy` to:
2358
2359	.. code-block:: c++
2360
2361	void foo.destroy(foo.Frame *frame) {
2362	frame->promise.~promise_type();
2363	delete frame;
2364	})reST";
2365
2366	static const char AttrDoc_CoroReturnType[] = R"reST(The ``[[clang::coro_return_type]]`` attribute is used to help static analyzers to recognize
2367	coroutines from the function signatures.
2368
2369	The ``coro_return_type`` attribute should be marked on a C++ class to mark it as
2370	a coroutine return type (CRT).
2371
2372	A function ``R func(P1, .., PN)`` has a coroutine return type (CRT) ``R`` if ``R``
2373	is marked by ``[[clang::coro_return_type]]`` and ``R`` has a promise type associated to it
2374	(i.e., std::coroutine_traits<R, P1, .., PN>::promise_type is a valid promise type).
2375
2376	If the return type of a function is a ``CRT`` then the function must be a coroutine.
2377	Otherwise the program is invalid. It is allowed for a non-coroutine to return a ``CRT``
2378	if the function is marked with ``[[clang::coro_wrapper]]``.
2379
2380	The ``[[clang::coro_wrapper]]`` attribute should be marked on a C++ function to mark it as
2381	a coroutine wrapper. A coroutine wrapper is a function which returns a ``CRT``,
2382	is not a coroutine itself and is marked with ``[[clang::coro_wrapper]]``.
2383
2384	Clang will enforce that all functions that return a ``CRT`` are either coroutines or marked
2385	with ``[[clang::coro_wrapper]]``. Clang will enforce this with an error.
2386
2387	From a language perspective, it is not possible to differentiate between a coroutine and a
2388	function returning a CRT by merely looking at the function signature.
2389
2390	Coroutine wrappers, in particular, are susceptible to capturing
2391	references to temporaries and other lifetime issues. This allows to avoid such lifetime
2392	issues with coroutine wrappers.
2393
2394	For example,
2395
2396	.. code-block:: c++
2397
2398	// This is a CRT.
2399	template <typename T> struct [[clang::coro_return_type]] Task {
2400	using promise_type = some_promise_type;
2401	};
2402
2403	Task<int> increment(int a) { co_return a + 1; } // Fine. This is a coroutine.
2404	Task<int> foo() { return increment(1); } // Error. foo is not a coroutine.
2405
2406	// Fine for a coroutine wrapper to return a CRT.
2407	[[clang::coro_wrapper]] Task<int> foo() { return increment(1); }
2408
2409	void bar() {
2410	// Invalid. This intantiates a function which returns a CRT but is not marked as
2411	// a coroutine wrapper.
2412	std::function<Task<int>(int)> f = increment;
2413	}
2414
2415	Note: ``a_promise_type::get_return_object`` is exempted from this analysis as it is a necessary
2416	implementation detail of any coroutine library.)reST";
2417
2418	static const char AttrDoc_CoroWrapper[] = R"reST(The ``[[clang::coro_return_type]]`` attribute is used to help static analyzers to recognize
2419	coroutines from the function signatures.
2420
2421	The ``coro_return_type`` attribute should be marked on a C++ class to mark it as
2422	a coroutine return type (CRT).
2423
2424	A function ``R func(P1, .., PN)`` has a coroutine return type (CRT) ``R`` if ``R``
2425	is marked by ``[[clang::coro_return_type]]`` and ``R`` has a promise type associated to it
2426	(i.e., std::coroutine_traits<R, P1, .., PN>::promise_type is a valid promise type).
2427
2428	If the return type of a function is a ``CRT`` then the function must be a coroutine.
2429	Otherwise the program is invalid. It is allowed for a non-coroutine to return a ``CRT``
2430	if the function is marked with ``[[clang::coro_wrapper]]``.
2431
2432	The ``[[clang::coro_wrapper]]`` attribute should be marked on a C++ function to mark it as
2433	a coroutine wrapper. A coroutine wrapper is a function which returns a ``CRT``,
2434	is not a coroutine itself and is marked with ``[[clang::coro_wrapper]]``.
2435
2436	Clang will enforce that all functions that return a ``CRT`` are either coroutines or marked
2437	with ``[[clang::coro_wrapper]]``. Clang will enforce this with an error.
2438
2439	From a language perspective, it is not possible to differentiate between a coroutine and a
2440	function returning a CRT by merely looking at the function signature.
2441
2442	Coroutine wrappers, in particular, are susceptible to capturing
2443	references to temporaries and other lifetime issues. This allows to avoid such lifetime
2444	issues with coroutine wrappers.
2445
2446	For example,
2447
2448	.. code-block:: c++
2449
2450	// This is a CRT.
2451	template <typename T> struct [[clang::coro_return_type]] Task {
2452	using promise_type = some_promise_type;
2453	};
2454
2455	Task<int> increment(int a) { co_return a + 1; } // Fine. This is a coroutine.
2456	Task<int> foo() { return increment(1); } // Error. foo is not a coroutine.
2457
2458	// Fine for a coroutine wrapper to return a CRT.
2459	[[clang::coro_wrapper]] Task<int> foo() { return increment(1); }
2460
2461	void bar() {
2462	// Invalid. This intantiates a function which returns a CRT but is not marked as
2463	// a coroutine wrapper.
2464	std::function<Task<int>(int)> f = increment;
2465	}
2466
2467	Note: ``a_promise_type::get_return_object`` is exempted from this analysis as it is a necessary
2468	implementation detail of any coroutine library.)reST";
2469
2470	static const char AttrDoc_CountedBy[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
2471	structure in C. The argument for the attribute is the name of a field member
2472	holding the count of elements in the flexible array. This information can be
2473	used to improve the results of the array bound sanitizer and the
2474	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
2475	within the same non-anonymous, enclosing struct as the flexible array member.
2476
2477	This example specifies that the flexible array member ``array`` has the number
2478	of elements allocated for it in ``count``:
2479
2480	.. code-block:: c
2481
2482	struct bar;
2483
2484	struct foo {
2485	size_t count;
2486	char other;
2487	struct bar *array[] __attribute__((counted_by(count)));
2488	};
2489
2490	This establishes a relationship between ``array`` and ``count``. Specifically,
2491	``array`` must have at least ``count`` number of elements available. It's the
2492	user's responsibility to ensure that this relationship is maintained through
2493	changes to the structure.
2494
2495	In the following example, the allocated array erroneously has fewer elements
2496	than what's specified by ``p->count``. This would result in an out-of-bounds
2497	access not being detected.
2498
2499	.. code-block:: c
2500
2501	#define SIZE_INCR 42
2502
2503	struct foo *p;
2504
2505	void foo_alloc(size_t count) {
2506	p = malloc(MAX(sizeof(struct foo),
2507	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2508	p->count = count + SIZE_INCR;
2509	}
2510
2511	The next example updates ``p->count``, but breaks the relationship requirement
2512	that ``p->array`` must have at least ``p->count`` number of elements available:
2513
2514	.. code-block:: c
2515
2516	#define SIZE_INCR 42
2517
2518	struct foo *p;
2519
2520	void foo_alloc(size_t count) {
2521	p = malloc(MAX(sizeof(struct foo),
2522	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2523	p->count = count;
2524	}
2525
2526	void use_foo(int index, int val) {
2527	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
2528	p->array[index] = val; /* The sanitizer can't properly check this access. */
2529	}
2530
2531	In this example, an update to ``p->count`` maintains the relationship
2532	requirement:
2533
2534	.. code-block:: c
2535
2536	void use_foo(int index, int val) {
2537	if (p->count == 0)
2538	return;
2539	--p->count;
2540	p->array[index] = val;
2541	})reST";
2542
2543	static const char AttrDoc_CountedByOrNull[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
2544	structure in C. The argument for the attribute is the name of a field member
2545	holding the count of elements in the flexible array. This information can be
2546	used to improve the results of the array bound sanitizer and the
2547	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
2548	within the same non-anonymous, enclosing struct as the flexible array member.
2549
2550	This example specifies that the flexible array member ``array`` has the number
2551	of elements allocated for it in ``count``:
2552
2553	.. code-block:: c
2554
2555	struct bar;
2556
2557	struct foo {
2558	size_t count;
2559	char other;
2560	struct bar *array[] __attribute__((counted_by(count)));
2561	};
2562
2563	This establishes a relationship between ``array`` and ``count``. Specifically,
2564	``array`` must have at least ``count`` number of elements available. It's the
2565	user's responsibility to ensure that this relationship is maintained through
2566	changes to the structure.
2567
2568	In the following example, the allocated array erroneously has fewer elements
2569	than what's specified by ``p->count``. This would result in an out-of-bounds
2570	access not being detected.
2571
2572	.. code-block:: c
2573
2574	#define SIZE_INCR 42
2575
2576	struct foo *p;
2577
2578	void foo_alloc(size_t count) {
2579	p = malloc(MAX(sizeof(struct foo),
2580	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2581	p->count = count + SIZE_INCR;
2582	}
2583
2584	The next example updates ``p->count``, but breaks the relationship requirement
2585	that ``p->array`` must have at least ``p->count`` number of elements available:
2586
2587	.. code-block:: c
2588
2589	#define SIZE_INCR 42
2590
2591	struct foo *p;
2592
2593	void foo_alloc(size_t count) {
2594	p = malloc(MAX(sizeof(struct foo),
2595	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2596	p->count = count;
2597	}
2598
2599	void use_foo(int index, int val) {
2600	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
2601	p->array[index] = val; /* The sanitizer can't properly check this access. */
2602	}
2603
2604	In this example, an update to ``p->count`` maintains the relationship
2605	requirement:
2606
2607	.. code-block:: c
2608
2609	void use_foo(int index, int val) {
2610	if (p->count == 0)
2611	return;
2612	--p->count;
2613	p->array[index] = val;
2614	})reST";
2615
2616	static const char AttrDoc_DLLExport[] = R"reST(The ``__declspec(dllexport)`` attribute declares a variable, function, or
2617	Objective-C interface to be exported from the module. It is available under the
2618	``-fdeclspec`` flag for compatibility with various compilers. The primary use
2619	is for COFF object files which explicitly specify what interfaces are available
2620	for external use. See the dllexport_ documentation on MSDN for more
2621	information.
2622
2623	.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx)reST";
2624
2625	static const char AttrDoc_DLLExportOnDecl[] = R"reST()reST";
2626
2627	static const char AttrDoc_DLLExportStaticLocal[] = R"reST()reST";
2628
2629	static const char AttrDoc_DLLImport[] = R"reST(The ``__declspec(dllimport)`` attribute declares a variable, function, or
2630	Objective-C interface to be imported from an external module. It is available
2631	under the ``-fdeclspec`` flag for compatibility with various compilers. The
2632	primary use is for COFF object files which explicitly specify what interfaces
2633	are imported from external modules. See the dllimport_ documentation on MSDN
2634	for more information.
2635
2636	Note that a dllimport function may still be inlined, if its definition is
2637	available and it doesn't reference any non-dllimport functions or global
2638	variables.
2639
2640	.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx)reST";
2641
2642	static const char AttrDoc_DLLImportStaticLocal[] = R"reST()reST";
2643
2644	static const char AttrDoc_Deprecated[] = R"reST(The ``deprecated`` attribute can be applied to a function, a variable, or a
2645	type. This is useful when identifying functions, variables, or types that are
2646	expected to be removed in a future version of a program.
2647
2648	Consider the function declaration for a hypothetical function ``f``:
2649
2650	.. code-block:: c++
2651
2652	void f(void) __attribute__((deprecated("message", "replacement")));
2653
2654	When spelled as ``__attribute__((deprecated))``, the deprecated attribute can have
2655	two optional string arguments. The first one is the message to display when
2656	emitting the warning; the second one enables the compiler to provide a Fix-It
2657	to replace the deprecated name with a new name. Otherwise, when spelled as
2658	``[[gnu::deprecated]]`` or ``[[deprecated]]``, the attribute can have one optional
2659	string argument which is the message to display when emitting the warning.)reST";
2660
2661	static const char AttrDoc_Destructor[] = R"reST(The ``constructor`` attribute causes the function to be called before entering
2662	``main()``, and the ``destructor`` attribute causes the function to be called
2663	after returning from ``main()`` or when the ``exit()`` function has been
2664	called. Note, ``quick_exit()``, ``_Exit()``, and ``abort()`` prevent a function
2665	marked ``destructor`` from being called.
2666
2667	The constructor or destructor function should not accept any arguments and its
2668	return type should be ``void``.
2669
2670	The attributes accept an optional argument used to specify the priority order
2671	in which to execute constructor and destructor functions. The priority is
2672	given as an integer constant expression between 101 and 65535 (inclusive).
2673	Priorities outside of that range are reserved for use by the implementation. A
2674	lower value indicates a higher priority of initialization. Note that only the
2675	relative ordering of values is important. For example:
2676
2677	.. code-block:: c++
2678
2679	__attribute__((constructor(200))) void foo(void);
2680	__attribute__((constructor(101))) void bar(void);
2681
2682	``bar()`` will be called before ``foo()``, and both will be called before
2683	``main()``. If no argument is given to the ``constructor`` or ``destructor``
2684	attribute, they default to the value ``65535``.)reST";
2685
2686	static const char AttrDoc_DeviceKernel[] = R"reST(These attributes specify that the function represents a kernel for device offloading.
2687	The specific semantics depend on the offloading language, target, and attribute spelling.
2688	Here is a code example using the attribute to mark a function as a kernel:
2689
2690	.. code-block:: c++
2691
2692	[[clang::device_kernel]] int foo(int x) { return ++x; })reST";
2693
2694	static const char AttrDoc_DiagnoseAsBuiltin[] = R"reST(The ``diagnose_as_builtin`` attribute indicates that Fortify diagnostics are to
2695	be applied to the declared function as if it were the function specified by the
2696	attribute. The builtin function whose diagnostics are to be mimicked should be
2697	given. In addition, the order in which arguments should be applied must also
2698	be given.
2699
2700	For example, the attribute can be used as follows.
2701
2702	.. code-block:: c
2703
2704	__attribute__((diagnose_as_builtin(__builtin_memset, 3, 2, 1)))
2705	void mymemset(int n, int c, void s) {
2706	// ...
2707	}
2708
2709	This indicates that calls to ``mymemset`` should be diagnosed as if they were
2710	calls to ``__builtin_memset``. The arguments ``3, 2, 1`` indicate by index the
2711	order in which arguments of ``mymemset`` should be applied to
2712	``__builtin_memset``. The third argument should be applied first, then the
2713	second, and then the first. Thus (when Fortify warnings are enabled) the call
2714	``mymemset(n, c, s)`` will diagnose overflows as if it were the call
2715	``__builtin_memset(s, c, n)``.
2716
2717	For variadic functions, the variadic arguments must come in the same order as
2718	they would to the builtin function, after all normal arguments. For instance,
2719	to diagnose a new function as if it were `sscanf`, we can use the attribute as
2720	follows.
2721
2722	.. code-block:: c
2723
2724	__attribute__((diagnose_as_builtin(sscanf, 1, 2)))
2725	int mysscanf(const char str, const char format, ...) {
2726	// ...
2727	}
2728
2729	Then the call `mysscanf("abc def", "%4s %4s", buf1, buf2)` will be diagnosed as
2730	if it were the call `sscanf("abc def", "%4s %4s", buf1, buf2)`.
2731
2732	This attribute cannot be applied to non-static member functions.)reST";
2733
2734	static const char AttrDoc_DiagnoseIf[] = R"reST(The ``diagnose_if`` attribute can be placed on function declarations to emit
2735	warnings or errors at compile-time if calls to the attributed function meet
2736	certain user-defined criteria. For example:
2737
2738	.. code-block:: c
2739
2740	int abs(int a)
2741	__attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
2742	int must_abs(int a)
2743	__attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
2744
2745	int val = abs(1); // warning: Redundant abs call
2746	int val2 = must_abs(1); // error: Redundant abs call
2747	int val3 = abs(val);
2748	int val4 = must_abs(val); // Because run-time checks are not emitted for
2749	// diagnose_if attributes, this executes without
2750	// issue.
2751
2752
2753	``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
2754
2755	* Overload resolution is not aware of ``diagnose_if`` attributes: they're
2756	considered only after we select the best candidate from a given candidate set.
2757	* Function declarations that differ only in their ``diagnose_if`` attributes are
2758	considered to be redeclarations of the same function (not overloads).
2759	* If the condition provided to ``diagnose_if`` cannot be evaluated, no
2760	diagnostic will be emitted.
2761
2762	Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
2763
2764	As a result of bullet number two, ``diagnose_if`` attributes will stack on the
2765	same function. For example:
2766
2767	.. code-block:: c
2768
2769	int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
2770	int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
2771
2772	int bar = foo(); // warning: diag1
2773	// warning: diag2
2774	int (*fooptr)(void) = foo; // warning: diag1
2775	// warning: diag2
2776
2777	constexpr int supportsAPILevel(int N) { return N < 5; }
2778	int baz(int a)
2779	__attribute__((diagnose_if(!supportsAPILevel(10),
2780	"Upgrade to API level 10 to use baz", "error")));
2781	int baz(int a)
2782	__attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
2783
2784	int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
2785	int v = baz(0); // error: Upgrade to API level 10 to use baz
2786
2787	Query for this feature with ``__has_attribute(diagnose_if)``.)reST";
2788
2789	static const char AttrDoc_DisableSanitizerInstrumentation[] = R"reST(Use the ``disable_sanitizer_instrumentation`` attribute on a function,
2790	Objective-C method, or global variable, to specify that no sanitizer
2791	instrumentation should be applied.
2792
2793	This is not the same as ``__attribute__((no_sanitize(...)))``, which depending
2794	on the tool may still insert instrumentation to prevent false positive reports.)reST";
2795
2796	static const char AttrDoc_DisableTailCalls[] = R"reST(The ``disable_tail_calls`` attribute instructs the backend to not perform tail
2797	call optimization inside the marked function.
2798
2799	For example:
2800
2801	.. code-block:: c
2802
2803	int callee(int);
2804
2805	int foo(int a) __attribute__((disable_tail_calls)) {
2806	return callee(a); // This call is not tail-call optimized.
2807	}
2808
2809	Marking virtual functions as ``disable_tail_calls`` is legal.
2810
2811	.. code-block:: c++
2812
2813	int callee(int);
2814
2815	class Base {
2816	public:
2817	[[clang::disable_tail_calls]] virtual int foo1() {
2818	return callee(); // This call is not tail-call optimized.
2819	}
2820	};
2821
2822	class Derived1 : public Base {
2823	public:
2824	int foo1() override {
2825	return callee(); // This call is tail-call optimized.
2826	}
2827	};)reST";
2828
2829	static const char AttrDoc_EmptyBases[] = R"reST(The empty_bases attribute permits the compiler to utilize the
2830	empty-base-optimization more frequently.
2831	This attribute only applies to struct, class, and union types.
2832	It is only supported when using the Microsoft C++ ABI.)reST";
2833
2834	static const char AttrDoc_EnableIf[] = R"reST(.. Note:: Some features of this attribute are experimental. The meaning of
2835	multiple enable_if attributes on a single declaration is subject to change in
2836	a future version of clang. Also, the ABI is not standardized and the name
2837	mangling may change in future versions. To avoid that, use asm labels.
2838
2839	The ``enable_if`` attribute can be placed on function declarations to control
2840	which overload is selected based on the values of the function's arguments.
2841	When combined with the ``overloadable`` attribute, this feature is also
2842	available in C.
2843
2844	.. code-block:: c++
2845
2846	int isdigit(int c);
2847	int isdigit(int c) __attribute__((enable_if(c <= -1 \|\| c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
2848
2849	void foo(char c) {
2850	isdigit(c);
2851	isdigit(10);
2852	isdigit(-10); // results in a compile-time error.
2853	}
2854
2855	The enable_if attribute takes two arguments, the first is an expression written
2856	in terms of the function parameters, the second is a string explaining why this
2857	overload candidate could not be selected to be displayed in diagnostics. The
2858	expression is part of the function signature for the purposes of determining
2859	whether it is a redeclaration (following the rules used when determining
2860	whether a C++ template specialization is ODR-equivalent), but is not part of
2861	the type.
2862
2863	The enable_if expression is evaluated as if it were the body of a
2864	bool-returning constexpr function declared with the arguments of the function
2865	it is being applied to, then called with the parameters at the call site. If the
2866	result is false or could not be determined through constant expression
2867	evaluation, then this overload will not be chosen and the provided string may
2868	be used in a diagnostic if the compile fails as a result.
2869
2870	Because the enable_if expression is an unevaluated context, there are no global
2871	state changes, nor the ability to pass information from the enable_if
2872	expression to the function body. For example, suppose we want calls to
2873	strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
2874	strbuf) only if the size of strbuf can be determined:
2875
2876	.. code-block:: c++
2877
2878	__attribute__((always_inline))
2879	static inline size_t strnlen(const char *s, size_t maxlen)
2880	__attribute__((overloadable))
2881	__attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
2882	"chosen when the buffer size is known but 'maxlen' is not")))
2883	{
2884	return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
2885	}
2886
2887	Multiple enable_if attributes may be applied to a single declaration. In this
2888	case, the enable_if expressions are evaluated from left to right in the
2889	following manner. First, the candidates whose enable_if expressions evaluate to
2890	false or cannot be evaluated are discarded. If the remaining candidates do not
2891	share ODR-equivalent enable_if expressions, the overload resolution is
2892	ambiguous. Otherwise, enable_if overload resolution continues with the next
2893	enable_if attribute on the candidates that have not been discarded and have
2894	remaining enable_if attributes. In this way, we pick the most specific
2895	overload out of a number of viable overloads using enable_if.
2896
2897	.. code-block:: c++
2898
2899	void f() __attribute__((enable_if(true, ""))); // #1
2900	void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
2901
2902	void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
2903	void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
2904
2905	In this example, a call to f() is always resolved to #2, as the first enable_if
2906	expression is ODR-equivalent for both declarations, but #1 does not have another
2907	enable_if expression to continue evaluating, so the next round of evaluation has
2908	only a single candidate. In a call to g(1, 1), the call is ambiguous even though
2909	#2 has more enable_if attributes, because the first enable_if expressions are
2910	not ODR-equivalent.
2911
2912	Query for this feature with ``__has_attribute(enable_if)``.
2913
2914	Note that functions with one or more ``enable_if`` attributes may not have
2915	their address taken, unless all of the conditions specified by said
2916	``enable_if`` are constants that evaluate to ``true``. For example:
2917
2918	.. code-block:: c
2919
2920	const int TrueConstant = 1;
2921	const int FalseConstant = 0;
2922	int f(int a) __attribute__((enable_if(a > 0, "")));
2923	int g(int a) __attribute__((enable_if(a == 0 \|\| a != 0, "")));
2924	int h(int a) __attribute__((enable_if(1, "")));
2925	int i(int a) __attribute__((enable_if(TrueConstant, "")));
2926	int j(int a) __attribute__((enable_if(FalseConstant, "")));
2927
2928	void fn() {
2929	int (*ptr)(int);
2930	ptr = &f; // error: 'a > 0' is not always true
2931	ptr = &g; // error: 'a == 0 \|\| a != 0' is not a truthy constant
2932	ptr = &h; // OK: 1 is a truthy constant
2933	ptr = &i; // OK: 'TrueConstant' is a truthy constant
2934	ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
2935	}
2936
2937	Because ``enable_if`` evaluation happens during overload resolution,
2938	``enable_if`` may give unintuitive results when used with templates, depending
2939	on when overloads are resolved. In the example below, clang will emit a
2940	diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``:
2941
2942	.. code-block:: c++
2943
2944	double foo(int i) __attribute__((enable_if(i > 0, "")));
2945	void *foo(int i) __attribute__((enable_if(i <= 0, "")));
2946	template <int I>
2947	auto bar() { return foo(I); }
2948
2949	template <typename T>
2950	auto baz() { return foo(T::number); }
2951
2952	struct WithNumber { constexpr static int number = 1; };
2953	void callThem() {
2954	bar<sizeof(WithNumber)>();
2955	baz<WithNumber>();
2956	}
2957
2958	This is because, in ``bar``, ``foo`` is resolved prior to template
2959	instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
2960	conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
2961	template instantiation, so the value for ``T::number`` is known.)reST";
2962
2963	static const char AttrDoc_EnforceTCB[] = R"reST(The ``enforce_tcb`` attribute can be placed on functions to enforce that a
2964	trusted compute base (TCB) does not call out of the TCB. This generates a
2965	warning every time a function not marked with an ``enforce_tcb`` attribute is
2966	called from a function with the ``enforce_tcb`` attribute. A function may be a
2967	part of multiple TCBs. Invocations through function pointers are currently
2968	not checked. Builtins are considered to a part of every TCB.
2969
2970	- ``enforce_tcb(Name)`` indicates that this function is a part of the TCB named ``Name``)reST";
2971
2972	static const char AttrDoc_EnforceTCBLeaf[] = R"reST(The ``enforce_tcb_leaf`` attribute satisfies the requirement enforced by
2973	``enforce_tcb`` for the marked function to be in the named TCB but does not
2974	continue to check the functions called from within the leaf function.
2975
2976	- ``enforce_tcb_leaf(Name)`` indicates that this function is a part of the TCB named ``Name``)reST";
2977
2978	static const char AttrDoc_EnumExtensibility[] = R"reST(Attribute ``enum_extensibility`` is used to distinguish between enum definitions
2979	that are extensible and those that are not. The attribute can take either
2980	``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
2981	enum type takes a value that corresponds to one of the enumerators listed in the
2982	enum definition or, when the enum is annotated with ``flag_enum``, a value that
2983	can be constructed using values corresponding to the enumerators. ``open``
2984	indicates a variable of the enum type can take any values allowed by the
2985	standard and instructs clang to be more lenient when issuing warnings.
2986
2987	.. code-block:: c
2988
2989	enum __attribute__((enum_extensibility(closed))) ClosedEnum {
2990	A0, A1
2991	};
2992
2993	enum __attribute__((enum_extensibility(open))) OpenEnum {
2994	B0, B1
2995	};
2996
2997	enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
2998	C0 = 1 << 0, C1 = 1 << 1
2999	};
3000
3001	enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
3002	D0 = 1 << 0, D1 = 1 << 1
3003	};
3004
3005	void foo1() {
3006	enum ClosedEnum ce;
3007	enum OpenEnum oe;
3008	enum ClosedFlagEnum cfe;
3009	enum OpenFlagEnum ofe;
3010
3011	ce = A1; // no warnings
3012	ce = 100; // warning issued
3013	oe = B1; // no warnings
3014	oe = 100; // no warnings
3015	cfe = C0 \| C1; // no warnings
3016	cfe = C0 \| C1 \| 4; // warning issued
3017	ofe = D0 \| D1; // no warnings
3018	ofe = D0 \| D1 \| 4; // no warnings
3019	})reST";
3020
3021	static const char AttrDoc_Error[] = R"reST(The ``error`` and ``warning`` function attributes can be used to specify a
3022	custom diagnostic to be emitted when a call to such a function is not
3023	eliminated via optimizations. This can be used to create compile time
3024	assertions that depend on optimizations, while providing diagnostics
3025	pointing to precise locations of the call site in the source.
3026
3027	.. code-block:: c++
3028
3029	__attribute__((warning("oh no"))) void dontcall();
3030	void foo() {
3031	if (someCompileTimeAssertionThatsTrue)
3032	dontcall(); // Warning
3033
3034	dontcall(); // Warning
3035
3036	if (someCompileTimeAssertionThatsFalse)
3037	dontcall(); // No Warning
3038	sizeof(dontcall()); // No Warning
3039	}
3040
3041	When the call occurs through inlined functions, the
3042	``-fdiagnostics-show-inlining-chain`` option can be used to show the
3043	inlining chain that led to the call. This helps identify which call site
3044	triggered the diagnostic when the attributed function is called from
3045	multiple locations through inline functions.
3046
3047	When enabled, this option automatically uses debug info for accurate source
3048	locations if available (``-gline-directives-only`` (implicitly enabled at
3049	``-g1``) or higher), or falls back to a heuristic based on metadata tracking.
3050	When falling back, a note is emitted suggesting ``-gline-directives-only`` for
3051	more accurate locations.)reST";
3052
3053	static const char AttrDoc_ExcludeFromExplicitInstantiation[] = R"reST(The ``exclude_from_explicit_instantiation`` attribute opts-out a member of a
3054	class template from being part of explicit template instantiations of that
3055	class template. This means that an explicit instantiation will not instantiate
3056	members of the class template marked with the attribute, but also that code
3057	where an extern template declaration of the enclosing class template is visible
3058	will not take for granted that an external instantiation of the class template
3059	would provide those members (which would otherwise be a link error, since the
3060	explicit instantiation won't provide those members). For example, let's say we
3061	don't want the ``data()`` method to be part of libc++'s ABI. To make sure it
3062	is not exported from the dylib, we give it hidden visibility:
3063
3064	.. code-block:: c++
3065
3066	// in <string>
3067	template <class CharT>
3068	class basic_string {
3069	public:
3070	__attribute__((__visibility__("hidden")))
3071	const value_type* data() const noexcept { ... }
3072	};
3073
3074	template class basic_string<char>;
3075
3076	Since an explicit template instantiation declaration for ``basic_string<char>``
3077	is provided, the compiler is free to assume that ``basic_string<char>::data()``
3078	will be provided by another translation unit, and it is free to produce an
3079	external call to this function. However, since ``data()`` has hidden visibility
3080	and the explicit template instantiation is provided in a shared library (as
3081	opposed to simply another translation unit), ``basic_string<char>::data()``
3082	won't be found and a link error will ensue. This happens because the compiler
3083	assumes that ``basic_string<char>::data()`` is part of the explicit template
3084	instantiation declaration, when it really isn't. To tell the compiler that
3085	``data()`` is not part of the explicit template instantiation declaration, the
3086	``exclude_from_explicit_instantiation`` attribute can be used:
3087
3088	.. code-block:: c++
3089
3090	// in <string>
3091	template <class CharT>
3092	class basic_string {
3093	public:
3094	__attribute__((__visibility__("hidden")))
3095	__attribute__((exclude_from_explicit_instantiation))
3096	const value_type* data() const noexcept { ... }
3097	};
3098
3099	template class basic_string<char>;
3100
3101	Now, the compiler won't assume that ``basic_string<char>::data()`` is provided
3102	externally despite there being an explicit template instantiation declaration:
3103	the compiler will implicitly instantiate ``basic_string<char>::data()`` in the
3104	TUs where it is used.
3105
3106	This attribute can be used on static and non-static member functions of class
3107	templates, static data members of class templates and member classes of class
3108	templates.
3109
3110	Interaction with __declspec(dllexport/dllimport)
3111
3112	For a DLL platform (i.e., Windows), this attribute also means "this member will
3113	never be exported or imported". Despite its name, this semantics applies to
3114	implicit instantiations and non-template entities as well.
3115
3116	.. code-block:: c++
3117
3118	// in <exception>
3119	class __declspec(dllimport) nested_exception {
3120	...
3121	public:
3122	__attribute__((exclude_from_explicit_instantiation))
3123	exception_ptr nested_ptr() const noexcept { ... }
3124	};
3125
3126	In this case, ``nested_exception::nested_ptr`` will never be attempted to be
3127	imported.)reST";
3128
3129	static const char AttrDoc_ExplicitInit[] = R"reST(The ``clang::require_explicit_initialization`` attribute indicates that a
3130	field of an aggregate must be initialized explicitly by the user when an object
3131	of the aggregate type is constructed. The attribute supports both C and C++,
3132	but its usage is invalid on non-aggregates.
3133
3134	Note that this attribute is not a memory safety feature, and is not intended
3135	to guard against use of uninitialized memory.
3136
3137	Rather, it is intended for use in "parameter-objects", used to simulate,
3138	for example, the passing of named parameters.
3139	Except inside unevaluated contexts, the attribute generates a warning when
3140	explicit initializers for such variables are not provided (this occurs
3141	regardless of whether any in-class field initializers exist):
3142
3143	.. code-block:: c++
3144
3145	struct Buffer {
3146	void *address [[clang::require_explicit_initialization]];
3147	size_t length [[clang::require_explicit_initialization]] = 0;
3148	};
3149
3150	struct ArrayIOParams {
3151	size_t count [[clang::require_explicit_initialization]];
3152	size_t element_size [[clang::require_explicit_initialization]];
3153	int flags = 0;
3154	};
3155
3156	size_t ReadArray(FILE *file, struct Buffer buffer,
3157	struct ArrayIOParams params);
3158
3159	int main() {
3160	unsigned int buf[512];
3161	ReadArray(stdin, {
3162	buf
3163	// warning: field 'length' is not explicitly initialized
3164	}, {
3165	.count = sizeof(buf) / sizeof(*buf),
3166	// warning: field 'element_size' is not explicitly initialized
3167	// (Note that a missing initializer for 'flags' is not diagnosed, because
3168	// the field is not marked as requiring explicit initialization.)
3169	});
3170	})reST";
3171
3172	static const char AttrDoc_ExtVectorType[] = R"reST(The ``ext_vector_type(N)`` attribute specifies that a type is a vector with N
3173	elements, directly mapping to an LLVM vector type. Originally from OpenCL, it
3174	allows element access the array subscript operator ``[]``, ``sN`` where N is
3175	a hexadecimal value, or ``x, y, z, w`` for graphics-style indexing.
3176	This attribute enables efficient SIMD operations and is usable in
3177	general-purpose code.
3178
3179	.. code-block:: c++
3180
3181	template <typename T, uint32_t N>
3182	constexpr T simd_reduce(T [[clang::ext_vector_type(N)]] v) {
3183	static_assert((N & (N - 1)) == 0, "N must be a power of two");
3184	if constexpr (N == 1)
3185	return v[0];
3186	else
3187	return simd_reduce<T, N / 2>(v.hi + v.lo);
3188	}
3189
3190	The vector type also supports swizzling up to sixteen elements. This can be done
3191	using the object accessors. The OpenCL documentation lists all of the accepted
3192	values.
3193
3194	.. code-block:: c++
3195
3196	using f16_x16 = _Float16 __attribute__((ext_vector_type(16)));
3197
3198	f16_x16 reverse(f16_x16 v) { return v.sfedcba9876543210; }
3199
3200	See the OpenCL documentation for some more complete examples.)reST";
3201
3202	static const char AttrDoc_ExternalSourceSymbol[] = R"reST(The ``external_source_symbol`` attribute specifies that a declaration originates
3203	from an external source and describes the nature of that source.
3204
3205	The fact that Clang is capable of recognizing declarations that were defined
3206	externally can be used to provide better tooling support for mixed-language
3207	projects or projects that rely on auto-generated code. For instance, an IDE that
3208	uses Clang and that supports mixed-language projects can use this attribute to
3209	provide a correct 'jump-to-definition' feature. For a concrete example,
3210	consider a protocol that's defined in a Swift file:
3211
3212	.. code-block:: swift
3213
3214	@objc public protocol SwiftProtocol {
3215	func method()
3216	}
3217
3218	This protocol can be used from Objective-C code by including a header file that
3219	was generated by the Swift compiler. The declarations in that header can use
3220	the ``external_source_symbol`` attribute to make Clang aware of the fact
3221	that ``SwiftProtocol`` actually originates from a Swift module:
3222
3223	.. code-block:: objc
3224
3225	__attribute__((external_source_symbol(language="Swift",defined_in="module")))
3226	@protocol SwiftProtocol
3227	@required
3228	- (void) method;
3229	@end
3230
3231	Consequently, when 'jump-to-definition' is performed at a location that
3232	references ``SwiftProtocol``, the IDE can jump to the original definition in
3233	the Swift source file rather than jumping to the Objective-C declaration in the
3234	auto-generated header file.
3235
3236	The ``external_source_symbol`` attribute is a comma-separated list that includes
3237	clauses that describe the origin and the nature of the particular declaration.
3238	Those clauses can be:
3239
3240	language=\ string-literal
3241	The name of the source language in which this declaration was defined.
3242
3243	defined_in=\ string-literal
3244	The name of the source container in which the declaration was defined. The
3245	exact definition of source container is language-specific, e.g. Swift's
3246	source containers are modules, so ``defined_in`` should specify the Swift
3247	module name.
3248
3249	USR=\ string-literal
3250	String that specifies a unified symbol resolution (USR) value for this
3251	declaration. USR string uniquely identifies this particular declaration, and
3252	is typically used when constructing an index of a codebase.
3253	The USR value in this attribute is expected to be generated by an external
3254	compiler that compiled the native declaration using its original source
3255	language. The exact format of the USR string and its other attributes
3256	are determined by the specification of this declaration's source language.
3257	When not specified, Clang's indexer will use the Clang USR for this symbol.
3258	User can query to see if Clang supports the use of the ``USR`` clause in
3259	the ``external_source_symbol`` attribute with
3260	``__has_attribute(external_source_symbol) >= 20230206``.
3261
3262	generated_declaration
3263	This declaration was automatically generated by some tool.
3264
3265	The clauses can be specified in any order. The clauses that are listed above are
3266	all optional, but the attribute has to have at least one clause.)reST";
3267
3268	static const char AttrDoc_FallThrough[] = R"reST(The ``fallthrough`` (or ``clang::fallthrough``) attribute is used
3269	to annotate intentional fall-through
3270	between switch labels. It can only be applied to a null statement placed at a
3271	point of execution between any statement and the next switch label. It is
3272	common to mark these places with a specific comment, but this attribute is
3273	meant to replace comments with a more strict annotation, which can be checked
3274	by the compiler. This attribute doesn't change semantics of the code and can
3275	be used wherever an intended fall-through occurs. It is designed to mimic
3276	control-flow statements like ``break;``, so it can be placed in most places
3277	where ``break;`` can, but only if there are no statements on the execution path
3278	between it and the next switch label.
3279
3280	By default, Clang does not warn on unannotated fallthrough from one ``switch``
3281	case to another. Diagnostics on fallthrough without a corresponding annotation
3282	can be enabled with the ``-Wimplicit-fallthrough`` argument.
3283
3284	Here is an example:
3285
3286	.. code-block:: c++
3287
3288	// compile with -Wimplicit-fallthrough
3289	switch (n) {
3290	case 22:
3291	case 33: // no warning: no statements between case labels
3292	f();
3293	case 44: // warning: unannotated fall-through
3294	g();
3295	[[clang::fallthrough]];
3296	case 55: // no warning
3297	if (x) {
3298	h();
3299	break;
3300	}
3301	else {
3302	i();
3303	[[clang::fallthrough]];
3304	}
3305	case 66: // no warning
3306	p();
3307	[[clang::fallthrough]]; // warning: fallthrough annotation does not
3308	// directly precede case label
3309	q();
3310	case 77: // warning: unannotated fall-through
3311	r();
3312	})reST";
3313
3314	static const char AttrDoc_FastCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
3315	function to use ECX and EDX as register parameters and clear parameters off of
3316	the stack on return. This convention does not support variadic calls or
3317	unprototyped functions in C, and has no effect on x86_64 targets. This calling
3318	convention is supported primarily for compatibility with existing code. Users
3319	seeking register parameters should use the ``regparm`` attribute, which does
3320	not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN.
3321
3322	.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx)reST";
3323
3324	static const char AttrDoc_Final[] = R"reST()reST";
3325
3326	static const char AttrDoc_FlagEnum[] = R"reST(This attribute can be added to an enumerator to signal to the compiler that it
3327	is intended to be used as a flag type. This will cause the compiler to assume
3328	that the range of the type includes all of the values that you can get by
3329	manipulating bits of the enumerator when issuing warnings.)reST";
3330
3331	static const char AttrDoc_Flatten[] = R"reST(The ``flatten`` attribute causes calls within the attributed function to
3332	be inlined unless it is impossible to do so, for example if the body of the
3333	callee is unavailable or if the callee has the ``noinline`` attribute.)reST";
3334
3335	static const char AttrDoc_Format[] = R"reST(Clang supports the ``format`` attribute, which indicates that the function
3336	accepts (among other possibilities) a ``printf`` or ``scanf``-like format string
3337	and corresponding arguments or a ``va_list`` that contains these arguments.
3338
3339	Please see `GCC documentation about format attribute
3340	<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
3341	about attribute syntax.
3342
3343	Clang implements two kinds of checks with this attribute.
3344
3345	#. Clang checks that the function with the ``format`` attribute is called with
3346	a format string that uses format specifiers that are allowed, and that
3347	arguments match the format string. This is the ``-Wformat`` warning, it is
3348	on by default.
3349
3350	#. Clang checks that the format string argument is a literal string. This is
3351	the ``-Wformat-nonliteral`` warning, it is off by default.
3352
3353	Clang implements this mostly the same way as GCC, but there is a difference
3354	for functions that accept a ``va_list`` argument (for example, ``vprintf``).
3355	GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
3356	functions. Clang does not warn if the format string comes from a function
3357	parameter, where the function is annotated with a compatible attribute,
3358	otherwise it warns. For example:
3359
3360	.. code-block:: c
3361
3362	__attribute__((__format__ (__scanf__, 1, 3)))
3363	void foo(const char* s, char *buf, ...) {
3364	va_list ap;
3365	va_start(ap, buf);
3366
3367	vprintf(s, ap); // warning: format string is not a string literal
3368	}
3369
3370	In this case we warn because ``s`` contains a format string for a
3371	``scanf``-like function, but it is passed to a ``printf``-like function.
3372
3373	If the attribute is removed, clang still warns, because the format string is
3374	not a string literal.
3375
3376	Another example:
3377
3378	.. code-block:: c
3379
3380	__attribute__((__format__ (__printf__, 1, 3)))
3381	void foo(const char* s, char *buf, ...) {
3382	va_list ap;
3383	va_start(ap, buf);
3384
3385	vprintf(s, ap); // warning
3386	}
3387
3388	In this case Clang does not warn because the format string ``s`` and
3389	the corresponding arguments are annotated. If the arguments are
3390	incorrect, the caller of ``foo`` will receive a warning.
3391
3392	As an extension to GCC's behavior, Clang accepts the ``format`` attribute on
3393	non-variadic functions. Clang checks non-variadic format functions for the same
3394	classes of issues that can be found on variadic functions, as controlled by the
3395	same warning flags, except that the types of formatted arguments is forced by
3396	the function signature. For example:
3397
3398	.. code-block:: c
3399
3400	__attribute__((__format__(__printf__, 1, 2)))
3401	void fmt(const char s, const char a, int b);
3402
3403	void bar(void) {
3404	fmt("%s %i", "hello", 123); // OK
3405	fmt("%i %g", "hello", 123); // warning: arguments don't match format
3406	extern const char *fmt;
3407	fmt(fmt, "hello", 123); // warning: format string is not a string literal
3408	}
3409
3410	When using the format attribute on a variadic function, the first data parameter
3411	_must_ be the index of the ellipsis in the parameter list. Clang will generate
3412	a diagnostic otherwise, as it wouldn't be possible to forward that argument list
3413	to `printf`-family functions. For instance, this is an error:
3414
3415	.. code-block:: c
3416
3417	__attribute__((__format__(__printf__, 1, 2)))
3418	void fmt(const char *s, int b, ...);
3419	// ^ error: format attribute parameter 3 is out of bounds
3420	// (must be __printf__, 1, 3)
3421
3422	Using the ``format`` attribute on a non-variadic function emits a GCC
3423	compatibility diagnostic.)reST";
3424
3425	static const char AttrDoc_FormatArg[] = R"reST(No documentation.)reST";
3426
3427	static const char AttrDoc_FormatMatches[] = R"reST(The ``format`` attribute is the basis for the enforcement of diagnostics in the
3428	``-Wformat`` family, but it only handles the case where the format string is
3429	passed along with the arguments it is going to format. It cannot handle the case
3430	where the format string and the format arguments are passed separately from each
3431	other. For instance:
3432
3433	.. code-block:: c
3434
3435	static const char *first_name;
3436	static double todays_temperature;
3437	static int wind_speed;
3438
3439	void say_hi(const char *fmt) {
3440	printf(fmt, first_name, todays_temperature);
3441	// ^ warning: format string is not a string literal
3442	printf(fmt, first_name, wind_speed);
3443	// ^ warning: format string is not a string literal
3444	}
3445
3446	int main() {
3447	say_hi("hello %s, it is %g degrees outside");
3448	say_hi("hello %s, it is %d degrees outside!");
3449	// ^ no diagnostic, but %d cannot format doubles
3450	}
3451
3452	In this example, ``fmt`` is expected to format a ``const char *`` and a
3453	``double``, but these values are not passed to ``say_hi``. Without the
3454	``format`` attribute (which cannot apply in this case), the -Wformat-nonliteral
3455	diagnostic unnecessarily triggers in the body of ``say_hi``, and incorrect
3456	``say_hi`` call sites do not trigger a diagnostic.
3457
3458	To complement the ``format`` attribute, Clang also defines the
3459	``format_matches`` attribute. Its syntax is similar to the ``format``
3460	attribute's, but instead of taking the index of the first formatted value
3461	argument, it takes a C string literal with the expected specifiers:
3462
3463	.. code-block:: c
3464
3465	static const char *first_name;
3466	static double todays_temperature;
3467	static int wind_speed;
3468
3469	__attribute__((__format_matches__(printf, 1, "%s %g")))
3470	void say_hi(const char *fmt) {
3471	printf(fmt, first_name, todays_temperature); // no dignostic
3472	printf(fmt, first_name, wind_speed); // warning: format specifies type 'int' but the argument has type 'double'
3473	}
3474
3475	int main() {
3476	say_hi("hello %s, it is %g degrees outside");
3477	say_hi("it is %g degrees outside, have a good day %s!");
3478	// warning: format specifies 'double' where 'const char *' is required
3479	// warning: format specifies 'const char *' where 'double' is required
3480	}
3481
3482	The third argument to ``format_matches`` is expected to evaluate to a **C string
3483	literal** even when the format string would normally be a different type for the
3484	given flavor, like a ``CFStringRef`` or a ``NSString *``.
3485
3486	The only requirement on the format string literal is that it has specifiers
3487	that are compatible with the arguments that will be used. It can contain
3488	arbitrary non-format characters. For instance, for the purposes of compile-time
3489	validation, ``"%s scored %g%% on her test"`` and ``"%s%g"`` are interchangeable
3490	as the format string argument. As a means of self-documentation, users may
3491	prefer the former when it provides a useful example of an expected format
3492	string.
3493
3494	In the implementation of a function with the ``format_matches`` attribute,
3495	format verification works as if the format string was identical to the one
3496	specified in the attribute.
3497
3498	.. code-block:: c
3499
3500	__attribute__((__format_matches__(printf, 1, "%s %g")))
3501	void say_hi(const char *fmt) {
3502	printf(fmt, "person", 546);
3503	// ^ warning: format specifies type 'double' but the
3504	// argument has type 'int'
3505	// note: format string is defined here:
3506	// __attribute__((__format_matches__(printf, 1, "%s %g")))
3507	// ^~
3508	}
3509
3510
3511	At the call sites of functions with the ``format_matches`` attribute, format
3512	verification instead compares the two format strings to evaluate their
3513	equivalence. Each format flavor defines equivalence between format specifiers.
3514	Generally speaking, two specifiers are equivalent if they format the same type.
3515	For instance, in the ``printf`` flavor, ``%2i`` and ``%-0.5d`` are compatible.
3516	When ``-Wformat-signedness`` is disabled, ``%d`` and ``%u`` are compatible. For
3517	a negative example, ``%ld`` is incompatible with ``%d``.
3518
3519	Do note the following un-obvious cases:
3520
3521	* Passing ``NULL`` as the format string does not trigger format diagnostics.
3522	* When the format string is not NULL, it cannot _miss_ specifiers, even in
3523	trailing positions. For instance, ``%d`` is not accepted when the required
3524	format is ``%d %d %d``.
3525	* While checks for the ``format`` attribute tolerate sone size mismatches
3526	that standard argument promotion renders immaterial (such as formatting an
3527	``int`` with ``%hhd``, which specifies a ``char``-sized integer), checks for
3528	``format_matches`` require specified argument sizes to match exactly.
3529	* Format strings expecting a variable modifier (such as ``%*s``) are
3530	incompatible with format strings that would itemize the variable modifiers
3531	(such as ``%i %s``), even if the two specify ABI-compatible argument lists.
3532	* All pointer specifiers, modifiers aside, are mutually incompatible. For
3533	instance, ``%s`` is not compatible with ``%p``, and ``%p`` is not compatible
3534	with ``%n``, and ``%hhn`` is incompatible with ``%s``, even if the pointers
3535	are ABI-compatible or identical on the selected platform. However, ``%0.5s``
3536	is compatible with ``%s``, since the difference only exists in modifier flags.
3537	This is not overridable with ``-Wformat-pedantic`` or its inverse, which
3538	control similar behavior in ``-Wformat``.
3539
3540	At this time, clang implements ``format_matches`` only for format types in the
3541	``printf`` family. This includes variants such as Apple's NSString format and
3542	the FreeBSD ``kprintf``, but excludes ``scanf``. Using a known but unsupported
3543	format silently fails in order to be compatible with other implementations that
3544	would support these formats.)reST";
3545
3546	static const char AttrDoc_FunctionReturnThunks[] = R"reST(The attribute ``function_return`` can replace return instructions with jumps to
3547	target-specific symbols. This attribute supports 2 possible values,
3548	corresponding to the values supported by the ``-mfunction-return=`` command
3549	line flag:
3550
3551	* ``__attribute__((function_return("keep")))`` to disable related transforms.
3552	This is useful for undoing global setting from ``-mfunction-return=`` locally
3553	for individual functions.
3554	* ``__attribute__((function_return("thunk-extern")))`` to replace returns with
3555	jumps, while NOT emitting the thunk.
3556
3557	The values ``thunk`` and ``thunk-inline`` from GCC are not supported.
3558
3559	The symbol used for ``thunk-extern`` is target specific:
3560	* X86: ``__x86_return_thunk``
3561
3562	As such, this function attribute is currently only supported on X86 targets.)reST";
3563
3564	static const char AttrDoc_GCCStruct[] = R"reST(The ``ms_struct`` and ``gcc_struct`` attributes request the compiler to enter a
3565	special record layout compatibility mode which mimics the layout of Microsoft or
3566	Itanium C++ ABI respectively. Obviously, if the current C++ ABI matches the
3567	requested ABI, the attribute does nothing. However, if it does not, annotated
3568	structure or class is laid out in a special compatibility mode, which slightly
3569	changes offsets for fields and bit-fields. The intention is to match the layout
3570	of the requested ABI for structures which only use C features.
3571
3572	Note that the default behavior can be controlled by ``-mms-bitfields`` and
3573	``-mno-ms-bitfields`` switches and via ``#pragma ms_struct``.
3574
3575	The primary difference is for bitfields, where the MS variant only packs
3576	adjacent fields into the same allocation unit if they have integral types
3577	of the same size, while the GCC/Itanium variant packs all fields in a bitfield
3578	tightly.)reST";
3579
3580	static const char AttrDoc_GNUInline[] = R"reST(The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline
3581	semantics, meaning:
3582
3583	* If any declaration that is declared ``inline`` is not declared ``extern``,
3584	then the ``inline`` keyword is just a hint. In particular, an out-of-line
3585	definition is still emitted for a function with external linkage, even if all
3586	call sites are inlined, unlike in C99 and C++ inline semantics.
3587
3588	* If all declarations that are declared ``inline`` are also declared
3589	``extern``, then the function body is present only for inlining and no
3590	out-of-line version is emitted.
3591
3592	Some important consequences: ``static inline`` emits an out-of-line
3593	version if needed, a plain ``inline`` definition emits an out-of-line version
3594	always, and an ``extern inline`` definition (in a header) followed by a
3595	(non-``extern``) ``inline`` declaration in a source file emits an out-of-line
3596	version of the function in that source file but provides the function body for
3597	inlining to all includers of the header.
3598
3599	Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or
3600	``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually
3601	exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline``
3602	function attribute can be used to get GNU inline semantics on a per function
3603	basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is
3604	already being compiled with GNU inline semantics as the implied default. It is
3605	unspecified which macro is defined in a C++ compilation.
3606
3607	GNU inline semantics are the default behavior with ``-std=gnu89``,
3608	``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``.)reST";
3609
3610	static const char AttrDoc_GuardedBy[] = R"reST(No documentation.)reST";
3611
3612	static const char AttrDoc_GuardedVar[] = R"reST(No documentation.)reST";
3613
3614	static const char AttrDoc_HIPManaged[] = R"reST(The ``__managed__`` attribute can be applied to a global variable declaration in HIP.
3615	A managed variable is emitted as an undefined global symbol in the device binary and is
3616	registered by ``__hipRegisterManagedVariable`` in init functions. The HIP runtime allocates
3617	managed memory and uses it to define the symbol when loading the device binary.
3618	A managed variable can be accessed in both device and host code.)reST";
3619
3620	static const char AttrDoc_HLSLAppliedSemantic[] = R"reST()reST";
3621
3622	static const char AttrDoc_HLSLAssociatedResourceDecl[] = R"reST()reST";
3623
3624	static const char AttrDoc_HLSLContainedType[] = R"reST()reST";
3625
3626	static const char AttrDoc_HLSLControlFlowHint[] = R"reST()reST";
3627
3628	static const char AttrDoc_HLSLGroupSharedAddressSpace[] = R"reST(HLSL enables threads of a compute shader to exchange values via shared memory.
3629	HLSL provides barrier primitives such as GroupMemoryBarrierWithGroupSync,
3630	and so on to ensure the correct ordering of reads and writes to shared memory
3631	in the shader and to avoid data races.
3632	Here's an example to declare a groupshared variable.
3633	.. code-block:: c++
3634
3635	groupshared GSData data[551];
3636
3637	The full documentation is available here: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-syntax#group-shared)reST";
3638
3639	static const char AttrDoc_HLSLIsCounter[] = R"reST()reST";
3640
3641	static const char AttrDoc_HLSLLoopHint[] = R"reST(The ``[loop]`` directive allows loop optimization hints to be
3642	specified for the subsequent loop. The directive allows unrolling to
3643	be disabled and is not compatible with [unroll(x)].
3644
3645	Specifying the parameter, ``[loop]``, directs the
3646	unroller to not unroll the loop.
3647
3648	.. code-block:: hlsl
3649
3650	[loop]
3651	for (...) {
3652	...
3653	}
3654
3655	.. code-block:: hlsl
3656
3657	[loop]
3658	while (...) {
3659	...
3660	}
3661
3662	.. code-block:: hlsl
3663
3664	[loop]
3665	do {
3666	...
3667	} while (...)
3668
3669	See `hlsl loop extensions <https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-for>`_
3670	for details.)reST";
3671
3672	static const char AttrDoc_HLSLNumThreads[] = R"reST(The ``numthreads`` attribute applies to HLSL shaders where explcit thread counts
3673	are required. The ``X``, ``Y``, and ``Z`` values provided to the attribute
3674	dictate the thread id. Total number of threads executed is ``X * Y * Z``.
3675
3676	The full documentation is available here: https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/sm5-attributes-numthreads)reST";
3677
3678	static const char AttrDoc_HLSLPackOffset[] = R"reST(The packoffset attribute is used to change the layout of a cbuffer.
3679	Attribute spelling in HLSL is: ``packoffset( c[Subcomponent][.component] )``.
3680	A subcomponent is a register number, which is an integer. A component is in the form of [.xyzw].
3681
3682	Examples:
3683
3684	.. code-block:: hlsl
3685
3686	cbuffer A {
3687	float3 a : packoffset(c0.y);
3688	float4 b : packoffset(c4);
3689	}
3690
3691	The full documentation is available here: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-packoffset)reST";
3692
3693	static const char AttrDoc_HLSLParamModifier[] = R"reST(HLSL function parameters are passed by value. Parameter declarations support
3694	three qualifiers to denote parameter passing behavior. The three qualifiers are
3695	`in`, `out` and `inout`.
3696
3697	Parameters annotated with `in` or with no annotation are passed by value from
3698	the caller to the callee.
3699
3700	Parameters annotated with `out` are written to the argument after the callee
3701	returns (Note: arguments values passed into `out` parameters are not copied
3702	into the callee).
3703
3704	Parameters annotated with `inout` are copied into the callee via a temporary,
3705	and copied back to the argument after the callee returns.)reST";
3706
3707	static const char AttrDoc_HLSLParsedSemantic[] = R"reST()reST";
3708
3709	static const char AttrDoc_HLSLROV[] = R"reST()reST";
3710
3711	static const char AttrDoc_HLSLRawBuffer[] = R"reST()reST";
3712
3713	static const char AttrDoc_HLSLResourceBinding[] = R"reST(The resource binding attribute sets the virtual register and logical register space for a resource.
3714	Attribute spelling in HLSL is: ``register(slot [, space])``.
3715	``slot`` takes the format ``[type][number]``,
3716	where ``type`` is a single character specifying the resource type and ``number`` is the virtual register number.
3717
3718	Register types are:
3719	t for shader resource views (SRV),
3720	s for samplers,
3721	u for unordered access views (UAV),
3722	b for constant buffer views (CBV).
3723
3724	Register space is specified in the format ``space[number]`` and defaults to ``space0`` if omitted.
3725	Here're resource binding examples with and without space:
3726
3727	.. code-block:: hlsl
3728
3729	RWBuffer<float> Uav : register(u3, space1);
3730	Buffer<float> Buf : register(t1);
3731
3732	The full documentation is available here: https://docs.microsoft.com/en-us/windows/win32/direct3d12/resource-binding-in-hlsl)reST";
3733
3734	static const char AttrDoc_HLSLResourceClass[] = R"reST()reST";
3735
3736	static const char AttrDoc_HLSLResourceDimension[] = R"reST()reST";
3737
3738	static const char AttrDoc_HLSLShader[] = R"reST(The ``shader`` type attribute applies to HLSL shader entry functions to
3739	identify the shader type for the entry function.
3740	The syntax is:
3741
3742	.. code-block:: text
3743
3744	``[shader(string-literal)]``
3745
3746	where the string literal is one of: "pixel", "vertex", "geometry", "hull",
3747	"domain", "compute", "raygeneration", "intersection", "anyhit", "closesthit",
3748	"miss", "callable", "mesh", "amplification". Normally the shader type is set
3749	by shader target with the ``-T`` option like ``-Tps_6_1``. When compiling to a
3750	library target like ``lib_6_3``, the shader type attribute can help the
3751	compiler to identify the shader type. It is mostly used by Raytracing shaders
3752	where shaders must be compiled into a library and linked at runtime.)reST";
3753
3754	static const char AttrDoc_HLSLUnparsedSemantic[] = R"reST()reST";
3755
3756	static const char AttrDoc_HLSLVkBinding[] = R"reST(The ``[[vk::binding]]`` attribute allows you to explicitly specify the descriptor
3757	set and binding for a resource when targeting SPIR-V. This is particularly
3758	useful when you need different bindings for SPIR-V and DXIL, as the ``register``
3759	attribute can be used for DXIL-specific bindings.
3760
3761	The attribute takes two integer arguments: the binding and the descriptor set.
3762	The descriptor set is optional and defaults to 0 if not provided.
3763
3764	.. code-block:: c++
3765
3766	// A structured buffer with binding 23 in descriptor set 102.
3767	[[vk::binding(23, 102)]] StructuredBuffer<float> Buf;
3768
3769	// A structured buffer with binding 14 in descriptor set 0.
3770	[[vk::binding(14)]] StructuredBuffer<float> Buf2;
3771
3772	// A cbuffer with binding 1 in descriptor set 2.
3773	[[vk::binding(1, 2)]] cbuffer MyCBuffer {
3774	float4x4 worldViewProj;
3775	};)reST";
3776
3777	static const char AttrDoc_HLSLVkConstantId[] = R"reST(The ``vk::constant_id`` attribute specifies the id for a SPIR-V specialization
3778	constant. The attribute applies to const global scalar variables. The variable must be initialized with a C++11 constexpr.
3779	In SPIR-V, the
3780	variable will be replaced with an `OpSpecConstant` with the given id.
3781	The syntax is:
3782
3783	.. code-block:: text
3784
3785	``[[vk::constant_id(<Id>)]] const T Name = <Init>``)reST";
3786
3787	static const char AttrDoc_HLSLVkExtBuiltinInput[] = R"reST(Vulkan shaders have `Input` builtins. Those variables are externally
3788	initialized by the driver/pipeline, but each copy is private to the current
3789	lane.
3790
3791	Those builtins can be declared using the `[[vk::ext_builtin_input]]` attribute
3792	like follows:
3793
3794	.. code-block:: c++
3795
3796	[[vk::ext_builtin_input(/* WorkgroupId */ 26)]]
3797	static const uint3 groupid;
3798
3799	This variable will be lowered into a module-level variable, with the `Input`
3800	storage class, and the `BuiltIn 26` decoration.
3801
3802	The full documentation for this inline SPIR-V attribute can be found here:
3803	https://github.com/microsoft/hlsl-specs/blob/main/proposals/0011-inline-spirv.md)reST";
3804
3805	static const char AttrDoc_HLSLVkExtBuiltinOutput[] = R"reST(Vulkan shaders have `Output` builtins. Those variables are externally
3806	visible to the driver/pipeline, but each copy is private to the current
3807	lane.
3808
3809	Those builtins can be declared using the `[[vk::ext_builtin_output]]`
3810	attribute like follows:
3811
3812	.. code-block:: c++
3813
3814	[[vk::ext_builtin_output(/* Position */ 0)]]
3815	static float4 position;
3816
3817	This variable will be lowered into a module-level variable, with the `Output`
3818	storage class, and the `BuiltIn 0` decoration.
3819
3820	The full documentation for this inline SPIR-V attribute can be found here:
3821	https://github.com/microsoft/hlsl-specs/blob/main/proposals/0011-inline-spirv.md)reST";
3822
3823	static const char AttrDoc_HLSLVkLocation[] = R"reST(Attribute used for specifying the location number for the stage input/output
3824	variables. Allowed on function parameters, function returns, and struct
3825	fields. This parameter has no effect when used outside of an entrypoint
3826	parameter/parameter field/return value.
3827
3828	This attribute maps to the 'Location' SPIR-V decoration.)reST";
3829
3830	static const char AttrDoc_HLSLVkPushConstant[] = R"reST(Vulkan shaders have `PushConstants`
3831
3832	The ``[[vk::push_constant]]`` attribute allows you to declare this
3833	global variable as a push constant when targeting Vulkan.
3834	This attribute is ignored otherwise.
3835
3836	This attribute must be applied to the variable, not underlying type.
3837	The variable type must be a struct, per the requirements of Vulkan, "there
3838	must be no more than one push constant block statically used per shader entry
3839	point.")reST";
3840
3841	static const char AttrDoc_HLSLWaveSize[] = R"reST(The ``WaveSize`` attribute specify a wave size on a shader entry point in order
3842	to indicate either that a shader depends on or strongly prefers a specific wave
3843	size.
3844	There're 2 versions of the attribute: ``WaveSize`` and ``RangedWaveSize``.
3845	The syntax for ``WaveSize`` is:
3846
3847	.. code-block:: text
3848
3849	``[WaveSize(<numLanes>)]``
3850
3851	The allowed wave sizes that an HLSL shader may specify are the powers of 2
3852	between 4 and 128, inclusive.
3853	In other words, the set: [4, 8, 16, 32, 64, 128].
3854
3855	The syntax for ``RangedWaveSize`` is:
3856
3857	.. code-block:: text
3858
3859	``[WaveSize(<minWaveSize>, <maxWaveSize>, [prefWaveSize])]``
3860
3861	Where minWaveSize is the minimum wave size supported by the shader representing
3862	the beginning of the allowed range, maxWaveSize is the maximum wave size
3863	supported by the shader representing the end of the allowed range, and
3864	prefWaveSize is the optional preferred wave size representing the size expected
3865	to be the most optimal for this shader.
3866
3867	``WaveSize`` is available for HLSL shader model 6.6 and later.
3868	``RangedWaveSize`` available for HLSL shader model 6.8 and later.
3869
3870	The full documentation is available here: https://microsoft.github.io/DirectX-Specs/d3d/HLSL_SM_6_6_WaveSize.html
3871	and https://microsoft.github.io/hlsl-specs/proposals/0013-wave-size-range.html)reST";
3872
3873	static const char AttrDoc_Hot[] = R"reST(``__attribute__((hot))`` marks a function as hot, as a manual alternative to PGO hotness data.
3874	If PGO data is available, the annotation ``__attribute__((hot))`` overrides the profile count based hotness (unlike ``__attribute__((cold))``).)reST";
3875
3876	static const char AttrDoc_HybridPatchable[] = R"reST(The ``hybrid_patchable`` attribute declares an ARM64EC function with an additional
3877	x86-64 thunk, which may be patched at runtime.
3878
3879	For more information see
3880	`ARM64EC ABI documentation <https://learn.microsoft.com/en-us/windows/arm/arm64ec-abi>`_.)reST";
3881
3882	static const char AttrDoc_IBAction[] = R"reST(No documentation.)reST";
3883
3884	static const char AttrDoc_IBOutlet[] = R"reST(No documentation.)reST";
3885
3886	static const char AttrDoc_IBOutletCollection[] = R"reST(No documentation.)reST";
3887
3888	static const char AttrDoc_IFunc[] = R"reST(``__attribute__((ifunc("resolver")))`` is used to mark that the address of a
3889	declaration should be resolved at runtime by calling a resolver function.
3890
3891	The symbol name of the resolver function is given in quotes. A function with
3892	this name (after mangling) must be defined in the current translation unit; it
3893	may be ``static``. The resolver function should return a pointer.
3894
3895	The ``ifunc`` attribute may only be used on a function declaration. A function
3896	declaration with an ``ifunc`` attribute is considered to be a definition of the
3897	declared entity. The entity must not have weak linkage; for example, in C++,
3898	it cannot be applied to a declaration if a definition at that location would be
3899	considered inline.
3900
3901	Not all targets support this attribute:
3902
3903	- ELF target support depends on both the linker and runtime linker, and is
3904	available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc
3905	v2.11.1 and later, and FreeBSD 9.1 and later.
3906	- Mach-O targets support it, but with slightly different semantics: the resolver
3907	is run at first call, instead of at load time by the runtime linker.
3908	- Windows target supports it on AArch64, but with different semantics: the
3909	``ifunc`` is replaced with a global function pointer, and the call is replaced
3910	with an indirect call. The function pointer is initialized by a constructor
3911	that calls the resolver.
3912	- Baremetal target supports it on AVR.
3913	- AIX/XCOFF supports it via a compiler-only solution. An ifunc appears as a
3914	regular function (has an entry point ``.foo[PR]`` and a function descriptor
3915	``foo[DS]``). The entry point is a stub that branches to the function address
3916	in the descriptor, and the descriptor is initialized via a constructor
3917	function (``__init_ifuncs``) that is linked into every shared object and
3918	executable. ``__init_ifuncs`` calls the resolver of each ifunc and stores the
3919	result in the corresponding descriptor.
3920	- Other targets currently do not support this attribute.)reST";
3921
3922	static const char AttrDoc_InferredNoReturn[] = R"reST()reST";
3923
3924	static const char AttrDoc_InitPriority[] = R"reST(In C++, the order in which global variables are initialized across translation
3925	units is unspecified, unlike the ordering within a single translation unit. The
3926	``init_priority`` attribute allows you to specify a relative ordering for the
3927	initialization of objects declared at namespace scope in C++ within a single
3928	linked image on supported platforms. The priority is given as an integer constant
3929	expression between 101 and 65535 (inclusive). Priorities outside of that range are
3930	reserved for use by the implementation. A lower value indicates a higher priority
3931	of initialization. Note that only the relative ordering of values is important.
3932	For example:
3933
3934	.. code-block:: c++
3935
3936	struct SomeType { SomeType(); };
3937	__attribute__((init_priority(200))) SomeType Obj1;
3938	__attribute__((init_priority(101))) SomeType Obj2;
3939
3940	``Obj2`` will be initialized before ``Obj1`` despite the usual order of
3941	initialization being the opposite.
3942
3943	Note that this attribute does not control the initialization order of objects
3944	across final linked image boundaries like shared objects and executables.
3945
3946	On Windows, ``init_seg(compiler)`` is represented with a priority of 200 and
3947	``init_seg(library)`` is represented with a priority of 400. ``init_seg(user)``
3948	uses the default 65535 priority.
3949
3950	On MachO platforms, this attribute also does not control the order of initialization
3951	across translation units, where it only affects the order within a single TU.
3952
3953	This attribute is only supported for C++ and Objective-C++ and is ignored in
3954	other language modes. Currently, this attribute is not implemented on z/OS.)reST";
3955
3956	static const char AttrDoc_InitSeg[] = R"reST(The attribute applied by ``pragma init_seg()`` controls the section into
3957	which global initialization function pointers are emitted. It is only
3958	available with ``-fms-extensions``. Typically, this function pointer is
3959	emitted into ``.CRT$XCU`` on Windows. The user can change the order of
3960	initialization by using a different section name with the same
3961	``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
3962	after the standard ``.CRT$XCU`` sections. See the init_seg_
3963	documentation on MSDN for more information.
3964
3965	.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx)reST";
3966
3967	static const char AttrDoc_IntelOclBicc[] = R"reST(No documentation.)reST";
3968
3969	static const char AttrDoc_InternalLinkage[] = R"reST(The ``internal_linkage`` attribute changes the linkage type of the declaration
3970	to internal. This is similar to C-style ``static``, but can be used on classes
3971	and class methods. When applied to a class definition, this attribute affects
3972	all methods and static data members of that class. This can be used to contain
3973	the ABI of a C++ library by excluding unwanted class methods from the export
3974	tables.)reST";
3975
3976	static const char AttrDoc_LTOVisibilityPublic[] = R"reST(See :doc:`LTOVisibility`.)reST";
3977
3978	static const char AttrDoc_LayoutVersion[] = R"reST(The layout_version attribute requests that the compiler utilize the class
3979	layout rules of a particular compiler version.
3980	This attribute only applies to struct, class, and union types.
3981	It is only supported when using the Microsoft C++ ABI.)reST";
3982
3983	static const char AttrDoc_Leaf[] = R"reST(The ``leaf`` attribute is used as a compiler hint to improve dataflow analysis
3984	in library functions. Functions marked with the ``leaf`` attribute are not allowed
3985	to jump back into the caller's translation unit, whether through invoking a
3986	callback function, an external function call, use of ``longjmp``, or other means.
3987	Therefore, they cannot use or modify any data that does not escape the caller function's
3988	compilation unit.
3989
3990	For more information see
3991	`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html>`)reST";
3992
3993	static const char AttrDoc_LifetimeBound[] = R"reST(The ``lifetimebound`` attribute on a function parameter or implicit object
3994	parameter indicates that objects that are referred to by that parameter may
3995	also be referred to by the return value of the annotated function (or, for a
3996	parameter of a constructor, by the value of the constructed object).
3997
3998	By default, a reference is considered to refer to its referenced object, a
3999	pointer is considered to refer to its pointee, a ``std::initializer_list<T>``
4000	is considered to refer to its underlying array, and aggregates (arrays and
4001	simple ``struct``\s) are considered to refer to all objects that their
4002	transitive subobjects refer to.
4003
4004	Clang warns if it is able to detect that an object or reference refers to
4005	another object with a shorter lifetime. For example, Clang will warn if a
4006	function returns a reference to a local variable, or if a reference is bound to
4007	a temporary object whose lifetime is not extended. By using the
4008	``lifetimebound`` attribute, this determination can be extended to look through
4009	user-declared functions. For example:
4010
4011	.. code-block:: c++
4012
4013	#include <map>
4014	#include <string>
4015
4016	using namespace std::literals;
4017
4018	// Returns m[key] if key is present, or default_value if not.
4019	template<typename T, typename U>
4020	const U &get_or_default(const std::map<T, U> &m [[clang::lifetimebound]],
4021	const T &key, /* note, not lifetimebound */
4022	const U &default_value [[clang::lifetimebound]]) {
4023	if (auto iter = m.find(key); iter != m.end()) return iter->second;
4024	else return default_value;
4025	}
4026
4027	int main() {
4028	std::map<std::string, std::string> m;
4029	// warning: temporary bound to local reference 'val1' will be destroyed
4030	// at the end of the full-expression
4031	const std::string &val1 = get_or_default(m, "foo"s, "bar"s);
4032
4033	// No warning in this case.
4034	std::string def_val = "bar"s;
4035	const std::string &val2 = get_or_default(m, "foo"s, def_val);
4036
4037	return 0;
4038	}
4039
4040	The attribute can be applied to the implicit ``this`` parameter of a member
4041	function by writing the attribute after the function type:
4042
4043	.. code-block:: c++
4044
4045	struct string {
4046	// The returned pointer should not outlive ``*this``.
4047	const char *data() const [[clang::lifetimebound]];
4048	};
4049
4050	This attribute is inspired by the C++ committee paper `P0936R0
4051	<http://wg21.link/p0936r0>`_, but does not affect whether temporary objects
4052	have their lifetimes extended.)reST";
4053
4054	static const char AttrDoc_LifetimeCaptureBy[] = R"reST(Similar to `lifetimebound`_, the ``lifetime_capture_by(X)`` attribute on a
4055	function parameter or implicit object parameter indicates that the capturing
4056	entity ``X`` may refer to the object referred by that parameter.
4057
4058	Below is a list of types of the parameters and what they're considered to refer to:
4059
4060	- A reference param (of non-view type) is considered to refer to its referenced object.
4061	- A pointer param (of non-view type) is considered to refer to its pointee.
4062	- View type param (type annotated with ``[[gsl::Pointer()]]``) is considered to refer
4063	to its pointee (gsl owner). This holds true even if the view type appears as a reference
4064	in the parameter. For example, both ``std::string_view`` and
4065	``const std::string_view &`` are considered to refer to a ``std::string``.
4066	- A ``std::initializer_list<T>`` is considered to refer to its underlying array.
4067	- Aggregates (arrays and simple ``struct``\s) are considered to refer to all
4068	objects that their transitive subobjects refer to.
4069
4070	Clang would diagnose when a temporary object is used as an argument to such an
4071	annotated parameter.
4072	In this case, the capturing entity ``X`` could capture a dangling reference to this
4073	temporary object.
4074
4075	.. code-block:: c++
4076
4077	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
4078	s.insert(a);
4079	}
4080	void use() {
4081	std::set<std::string_view> s;
4082	addToSet(std::string(), s); // Warning: object whose reference is captured by 's' will be destroyed at the end of the full-expression.
4083	// ^^^^^^^^^^^^^
4084	std::string local;
4085	addToSet(local, s); // Ok.
4086	}
4087
4088	The capturing entity ``X`` can be one of the following:
4089
4090	- Another (named) function parameter.
4091
4092	.. code-block:: c++
4093
4094	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
4095	s.insert(a);
4096	}
4097
4098	- ``this`` (in case of member functions).
4099
4100	.. code-block:: c++
4101
4102	class S {
4103	void addToSet(std::string_view a [[clang::lifetime_capture_by(this)]]) {
4104	s.insert(a);
4105	}
4106	std::set<std::string_view> s;
4107	};
4108
4109	Note: When applied to a constructor parameter, `[[clang::lifetime_capture_by(this)]]` is just an alias of `[[clang::lifetimebound]]`.
4110
4111	- `global`, `unknown`.
4112
4113	.. code-block:: c++
4114
4115	std::set<std::string_view> s;
4116	void addToSet(std::string_view a [[clang::lifetime_capture_by(global)]]) {
4117	s.insert(a);
4118	}
4119	void addSomewhere(std::string_view a [[clang::lifetime_capture_by(unknown)]]);
4120
4121	The attribute can be applied to the implicit ``this`` parameter of a member
4122	function by writing the attribute after the function type:
4123
4124	.. code-block:: c++
4125
4126	struct S {
4127	const char data(std::set<S>& s) [[clang::lifetime_capture_by(s)]] {
4128	s.insert(this);
4129	}
4130	};
4131
4132	The attribute supports specifying more than one capturing entities:
4133
4134	.. code-block:: c++
4135
4136	void addToSets(std::string_view a [[clang::lifetime_capture_by(s1, s2)]],
4137	std::set<std::string_view>& s1,
4138	std::set<std::string_view>& s2) {
4139	s1.insert(a);
4140	s2.insert(a);
4141	}
4142
4143	Limitation: The capturing entity ``X`` is not used by the analysis and is
4144	used for documentation purposes only. This is because the analysis is
4145	statement-local and only detects use of a temporary as an argument to the
4146	annotated parameter.
4147
4148	.. code-block:: c++
4149
4150	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s);
4151	void use() {
4152	std::set<std::string_view> s;
4153	if (foo()) {
4154	std::string str;
4155	addToSet(str, s); // Not detected.
4156	}
4157	})reST";
4158
4159	static const char AttrDoc_Likely[] = R"reST(The ``likely`` and ``unlikely`` attributes are used as compiler hints.
4160	The attributes are used to aid the compiler to determine which branch is
4161	likely or unlikely to be taken. This is done by marking the branch substatement
4162	with one of the two attributes.
4163
4164	It isn't allowed to annotate a single statement with both ``likely`` and
4165	``unlikely``. Annotating the ``true`` and ``false`` branch of an ``if``
4166	statement with the same likelihood attribute will result in a diagnostic and
4167	the attributes are ignored on both branches.
4168
4169	In a ``switch`` statement it's allowed to annotate multiple ``case`` labels
4170	or the ``default`` label with the same likelihood attribute. This makes
4171	* all labels without an attribute have a neutral likelihood,
4172	* all labels marked ``[[likely]]`` have an equally positive likelihood, and
4173	* all labels marked ``[[unlikely]]`` have an equally negative likelihood.
4174	The neutral likelihood is the more likely of path execution than the negative
4175	likelihood. The positive likelihood is the more likely of path of execution
4176	than the neutral likelihood.
4177
4178	These attributes have no effect on the generated code when using
4179	PGO (Profile-Guided Optimization) or at optimization level 0.
4180
4181	In Clang, the attributes will be ignored if they're not placed on
4182	* the ``case`` or ``default`` label of a ``switch`` statement,
4183	* or on the substatement of an ``if`` or ``else`` statement,
4184	* or on the substatement of an ``for`` or ``while`` statement.
4185	The C++ Standard recommends to honor them on every statement in the
4186	path of execution, but that can be confusing:
4187
4188	.. code-block:: c++
4189
4190	if (b) {
4191	[[unlikely]] --b; // Per the standard this is in the path of
4192	// execution, so this branch should be considered
4193	// unlikely. However, Clang ignores the attribute
4194	// here since it is not on the substatement.
4195	}
4196
4197	if (b) {
4198	--b;
4199	if(b)
4200	return;
4201	[[unlikely]] --b; // Not in the path of execution,
4202	} // the branch has no likelihood information.
4203
4204	if (b) {
4205	--b;
4206	foo(b);
4207	// Whether or not the next statement is in the path of execution depends
4208	// on the declaration of foo():
4209	// In the path of execution: void foo(int);
4210	// Not in the path of execution: [[noreturn]] void foo(int);
4211	// This means the likelihood of the branch depends on the declaration
4212	// of foo().
4213	[[unlikely]] --b;
4214	}
4215
4216
4217	Below are some example usages of the likelihood attributes and their effects:
4218
4219	.. code-block:: c++
4220
4221	if (b) [[likely]] { // Placement on the first statement in the branch.
4222	// The compiler will optimize to execute the code here.
4223	} else {
4224	}
4225
4226	if (b)
4227	[[unlikely]] b++; // Placement on the first statement in the branch.
4228	else {
4229	// The compiler will optimize to execute the code here.
4230	}
4231
4232	if (b) {
4233	[[unlikely]] b++; // Placement on the second statement in the branch.
4234	} // The attribute will be ignored.
4235
4236	if (b) [[likely]] {
4237	[[unlikely]] b++; // No contradiction since the second attribute
4238	} // is ignored.
4239
4240	if (b)
4241	;
4242	else [[likely]] {
4243	// The compiler will optimize to execute the code here.
4244	}
4245
4246	if (b)
4247	;
4248	else
4249	// The compiler will optimize to execute the next statement.
4250	[[likely]] b = f();
4251
4252	if (b) [[likely]]; // Both branches are likely. A diagnostic is issued
4253	else [[likely]]; // and the attributes are ignored.
4254
4255	if (b)
4256	[[likely]] int i = 5; // Issues a diagnostic since the attribute
4257	// isn't allowed on a declaration.
4258
4259	switch (i) {
4260	[[likely]] case 1: // This value is likely
4261	...
4262	break;
4263
4264	[[unlikely]] case 2: // This value is unlikely
4265	...
4266	[[fallthrough]];
4267
4268	case 3: // No likelihood attribute
4269	...
4270	[[likely]] break; // No effect
4271
4272	case 4: [[likely]] { // attribute on substatement has no effect
4273	...
4274	break;
4275	}
4276
4277	[[unlikely]] default: // All other values are unlikely
4278	...
4279	break;
4280	}
4281
4282	switch (i) {
4283	[[likely]] case 0: // This value and code path is likely
4284	...
4285	[[fallthrough]];
4286
4287	case 1: // No likelihood attribute, code path is neutral
4288	break; // falling through has no effect on the likelihood
4289
4290	case 2: // No likelihood attribute, code path is neutral
4291	[[fallthrough]];
4292
4293	[[unlikely]] default: // This value and code path are both unlikely
4294	break;
4295	}
4296
4297	for(int i = 0; i != size; ++i) [[likely]] {
4298	... // The loop is the likely path of execution
4299	}
4300
4301	for(const auto &E : Elements) [[likely]] {
4302	... // The loop is the likely path of execution
4303	}
4304
4305	while(i != size) [[unlikely]] {
4306	... // The loop is the unlikely path of execution
4307	} // The generated code will optimize to skip the loop body
4308
4309	while(true) [[unlikely]] {
4310	... // The attribute has no effect
4311	} // Clang elides the comparison and generates an infinite
4312	// loop)reST";
4313
4314	static const char AttrDoc_LoaderUninitialized[] = R"reST(The ``loader_uninitialized`` attribute can be placed on global variables to
4315	indicate that the variable does not need to be zero initialized by the loader.
4316	On most targets, zero-initialization does not incur any additional cost.
4317	For example, most general purpose operating systems deliberately ensure
4318	that all memory is properly initialized in order to avoid leaking privileged
4319	information from the kernel or other programs. However, some targets
4320	do not make this guarantee, and on these targets, avoiding an unnecessary
4321	zero-initialization can have a significant impact on load times and/or code
4322	size.
4323
4324	A declaration with this attribute is a non-tentative definition just as if it
4325	provided an initializer. Variables with this attribute are considered to be
4326	uninitialized in the same sense as a local variable, and the programs must
4327	write to them before reading from them. If the variable's type is a C++ class
4328	type with a non-trivial default constructor, or an array thereof, this attribute
4329	only suppresses the static zero-initialization of the variable, not the dynamic
4330	initialization provided by executing the default constructor.)reST";
4331
4332	static const char AttrDoc_LockReturned[] = R"reST(No documentation.)reST";
4333
4334	static const char AttrDoc_LocksExcluded[] = R"reST(No documentation.)reST";
4335
4336	static const char AttrDoc_LoopHint[] = R"reST(The ``#pragma clang loop`` directive allows loop optimization hints to be
4337	specified for the subsequent loop. The directive allows pipelining to be
4338	disabled, or vectorization, vector predication, interleaving, and unrolling to
4339	be enabled or disabled. Vector width, vector predication, interleave count,
4340	unrolling count, and the initiation interval for pipelining can be explicitly
4341	specified. See `language extensions
4342	<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
4343	for details.)reST";
4344
4345	static const char AttrDoc_M68kInterrupt[] = R"reST(No documentation.)reST";
4346
4347	static const char AttrDoc_M68kRTD[] = R"reST(On M68k targets, this attribute changes the calling convention of a function
4348	to clear parameters off the stack on return. In other words, callee is
4349	responsible for cleaning out the stack space allocated for incoming paramters.
4350	This convention does not support variadic calls or unprototyped functions in C.
4351	When targeting M68010 or newer CPUs, this calling convention is implemented
4352	using the `rtd` instruction.)reST";
4353
4354	static const char AttrDoc_MIGServerRoutine[] = R"reST(The Mach Interface Generator release-on-success convention dictates
4355	functions that follow it to only release arguments passed to them when they
4356	return "success" (a ``kern_return_t`` error code that indicates that
4357	no errors have occurred). Otherwise the release is performed by the MIG client
4358	that called the function. The annotation ``__attribute__((mig_server_routine))``
4359	is applied in order to specify which functions are expected to follow the
4360	convention. This allows the Static Analyzer to find bugs caused by violations of
4361	that convention. The attribute would normally appear on the forward declaration
4362	of the actual server routine in the MIG server header, but it may also be
4363	added to arbitrary functions that need to follow the same convention - for
4364	example, a user can add them to auxiliary functions called by the server routine
4365	that have their return value of type ``kern_return_t`` unconditionally returned
4366	from the routine. The attribute can be applied to C++ methods, and in this case
4367	it will be automatically applied to overrides if the method is virtual. The
4368	attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``.)reST";
4369
4370	static const char AttrDoc_MSABI[] = R"reST(On non-Windows x86_64 and aarch64 targets, this attribute changes the calling convention of
4371	a function to match the default convention used on Windows. This
4372	attribute has no effect on Windows targets or non-x86_64, non-aarch64 targets.)reST";
4373
4374	static const char AttrDoc_MSAllocator[] = R"reST(The ``__declspec(allocator)`` attribute is applied to functions that allocate
4375	memory, such as operator new in C++. When CodeView debug information is emitted
4376	(enabled by ``clang -gcodeview`` or ``clang-cl /Z7``), Clang will attempt to
4377	record the code offset of heap allocation call sites in the debug info. It will
4378	also record the type being allocated using some local heuristics. The Visual
4379	Studio debugger uses this information to `profile memory usage`_.
4380
4381	.. _profile memory usage: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage
4382
4383	This attribute does not affect optimizations in any way, unlike GCC's
4384	``__attribute__((malloc))``.)reST";
4385
4386	static const char AttrDoc_MSConstexpr[] = R"reST(The ``[[msvc::constexpr]]`` attribute can be applied only to a function
4387	definition or a ``return`` statement. It does not impact function declarations.
4388	A ``[[msvc::constexpr]]`` function cannot be ``constexpr`` or ``consteval``.
4389	A ``[[msvc::constexpr]]`` function is treated as if it were a ``constexpr`` function
4390	when it is evaluated in a constant context of ``[[msvc::constexpr]] return`` statement.
4391	Otherwise, it is treated as a regular function.
4392
4393	Semantics of this attribute are enabled only under MSVC compatibility
4394	(``-fms-compatibility-version``) 19.33 and later.)reST";
4395
4396	static const char AttrDoc_MSInheritance[] = R"reST(This collection of keywords is enabled under ``-fms-extensions`` and controls
4397	the pointer-to-member representation used on ``--win32`` targets.
4398
4399	The ``--win32`` targets utilize a pointer-to-member representation which
4400	varies in size and alignment depending on the definition of the underlying
4401	class.
4402
4403	However, this is problematic when a forward declaration is only available and
4404	no definition has been made yet. In such cases, Clang is forced to utilize the
4405	most general representation that is available to it.
4406
4407	These keywords make it possible to use a pointer-to-member representation other
4408	than the most general one regardless of whether or not the definition will ever
4409	be present in the current translation unit.
4410
4411	This family of keywords belong between the ``class-key`` and ``class-name``:
4412
4413	.. code-block:: c++
4414
4415	struct __single_inheritance S;
4416	int S::*i;
4417	struct S {};
4418
4419	This keyword can be applied to class templates but only has an effect when used
4420	on full specializations:
4421
4422	.. code-block:: c++
4423
4424	template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
4425	template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
4426	template <> struct __single_inheritance A<int, float>;
4427
4428	Note that choosing an inheritance model less general than strictly necessary is
4429	an error:
4430
4431	.. code-block:: c++
4432
4433	struct __multiple_inheritance S; // error: inheritance model does not match definition
4434	int S::*i;
4435	struct S {};)reST";
4436
4437	static const char AttrDoc_MSNoVTable[] = R"reST(This attribute can be added to a class declaration or definition to signal to
4438	the compiler that constructors and destructors will not reference the virtual
4439	function table. It is only supported when using the Microsoft C++ ABI.)reST";
4440
4441	static const char AttrDoc_MSP430Interrupt[] = R"reST(No documentation.)reST";
4442
4443	static const char AttrDoc_MSStruct[] = R"reST(The ``ms_struct`` and ``gcc_struct`` attributes request the compiler to enter a
4444	special record layout compatibility mode which mimics the layout of Microsoft or
4445	Itanium C++ ABI respectively. Obviously, if the current C++ ABI matches the
4446	requested ABI, the attribute does nothing. However, if it does not, annotated
4447	structure or class is laid out in a special compatibility mode, which slightly
4448	changes offsets for fields and bit-fields. The intention is to match the layout
4449	of the requested ABI for structures which only use C features.
4450
4451	Note that the default behavior can be controlled by ``-mms-bitfields`` and
4452	``-mno-ms-bitfields`` switches and via ``#pragma ms_struct``.
4453
4454	The primary difference is for bitfields, where the MS variant only packs
4455	adjacent fields into the same allocation unit if they have integral types
4456	of the same size, while the GCC/Itanium variant packs all fields in a bitfield
4457	tightly.)reST";
4458
4459	static const char AttrDoc_MSVtorDisp[] = R"reST()reST";
4460
4461	static const char AttrDoc_MallocSpan[] = R"reST(The ``malloc_span`` attribute can be used to mark that a function which acts
4462	like a system memory allocation function and returns a span-like structure,
4463	where the returned memory range does not alias storage from any other object
4464	accessible to the caller.
4465
4466	In this context, a span-like structure is assumed to have two non-static data
4467	members, one of which is a pointer to the start of the allocated memory and
4468	the other one is either an integer type containing the size of the actually
4469	allocated memory or a pointer to the end of the allocated region. Note, static
4470	data members do not impact whether a type is span-like or not.)reST";
4471
4472	static const char AttrDoc_MaxFieldAlignment[] = R"reST()reST";
4473
4474	static const char AttrDoc_MayAlias[] = R"reST(No documentation.)reST";
4475
4476	static const char AttrDoc_MaybeUndef[] = R"reST(The ``maybe_undef`` attribute can be placed on a function parameter. It indicates
4477	that the parameter is allowed to use undef values. It informs the compiler
4478	to insert a freeze LLVM IR instruction on the function parameter.
4479	Please note that this is an attribute that is used as an internal
4480	implementation detail and not intended to be used by external users.
4481
4482	In languages HIP, CUDA etc., some functions have multi-threaded semantics and
4483	it is enough for only one or some threads to provide defined arguments.
4484	Depending on semantics, undef arguments in some threads don't produce
4485	undefined results in the function call. Since, these functions accept undefined
4486	arguments, ``maybe_undef`` attribute can be placed.
4487
4488	Sample usage:
4489	.. code-block:: c
4490
4491	void maybeundeffunc(int __attribute__((maybe_undef))param);)reST";
4492
4493	static const char AttrDoc_MicroMips[] = R"reST(Clang supports the GNU style ``__attribute__((micromips))`` and
4494	``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
4495	may be attached to a function definition and instructs the backend to generate
4496	or not to generate microMIPS code for that function.
4497
4498	These attributes override the ``-mmicromips`` and ``-mno-micromips`` options
4499	on the command line.)reST";
4500
4501	static const char AttrDoc_MinSize[] = R"reST(This function attribute indicates that optimization passes and code generator passes
4502	make choices that keep the function code size as small as possible. Optimizations may
4503	also sacrifice runtime performance in order to minimize the size of the generated code.)reST";
4504
4505	static const char AttrDoc_MinVectorWidth[] = R"reST(Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This
4506	attribute may be attached to a function and informs the backend that this
4507	function desires vectors of at least this width to be generated. Target-specific
4508	maximum vector widths still apply. This means even if you ask for something
4509	larger than the target supports, you will only get what the target supports.
4510	This attribute is meant to be a hint to control target heuristics that may
4511	generate narrower vectors than what the target hardware supports.
4512
4513	This is currently used by the X86 target to allow some CPUs that support 512-bit
4514	vectors to be limited to using 256-bit vectors to avoid frequency penalties.
4515	This is currently enabled with the ``-prefer-vector-width=256`` command line
4516	option. The ``min_vector_width`` attribute can be used to prevent the backend
4517	from trying to split vector operations to match the ``prefer-vector-width``. All
4518	X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
4519	use of any of the X86-specific vector builtins will implicitly set this
4520	attribute on the calling function. The intent is that explicitly writing vector
4521	code using the X86 intrinsics will prevent ``prefer-vector-width`` from
4522	affecting the code.)reST";
4523
4524	static const char AttrDoc_Mips16[] = R"reST(No documentation.)reST";
4525
4526	static const char AttrDoc_MipsInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on
4527	MIPS targets. This attribute may be attached to a function definition and instructs
4528	the backend to generate appropriate function entry/exit code so that it can be used
4529	directly as an interrupt service routine.
4530
4531	By default, the compiler will produce a function prologue and epilogue suitable for
4532	an interrupt service routine that handles an External Interrupt Controller (eic)
4533	generated interrupt. This behavior can be explicitly requested with the "eic"
4534	argument.
4535
4536	Otherwise, for use with vectored interrupt mode, the argument passed should be
4537	of the form "vector=LEVEL" where LEVEL is one of the following values:
4538	"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
4539	then set the interrupt mask to the corresponding level which will mask all
4540	interrupts up to and including the argument.
4541
4542	The semantics are as follows:
4543
4544	- The prologue is modified so that the Exception Program Counter (EPC) and
4545	Status coprocessor registers are saved to the stack. The interrupt mask is
4546	set so that the function can only be interrupted by a higher priority
4547	interrupt. The epilogue will restore the previous values of EPC and Status.
4548
4549	- The prologue and epilogue are modified to save and restore all non-kernel
4550	registers as necessary.
4551
4552	- The FPU is disabled in the prologue, as the floating pointer registers are not
4553	spilled to the stack.
4554
4555	- The function return sequence is changed to use an exception return instruction.
4556
4557	- The parameter sets the interrupt mask for the function corresponding to the
4558	interrupt level specified. If no mask is specified the interrupt mask
4559	defaults to "eic".)reST";
4560
4561	static const char AttrDoc_MipsLongCall[] = R"reST(Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
4562	and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
4563	only be added to function declarations and change the code generated
4564	by the compiler when directly calling the function. The ``near`` attribute
4565	allows calls to the function to be made using the ``jal`` instruction, which
4566	requires the function to be located in the same naturally aligned 256MB
4567	segment as the caller. The ``long_call`` and ``far`` attributes are synonyms
4568	and require the use of a different call sequence that works regardless
4569	of the distance between the functions.
4570
4571	These attributes have no effect for position-independent code.
4572
4573	These attributes take priority over command line switches such
4574	as ``-mlong-calls`` and ``-mno-long-calls``.)reST";
4575
4576	static const char AttrDoc_MipsShortCall[] = R"reST(Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
4577	``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
4578	on MIPS targets. These attributes may only be added to function declarations
4579	and change the code generated by the compiler when directly calling
4580	the function. The ``short_call`` and ``near`` attributes are synonyms and
4581	allow calls to the function to be made using the ``jal`` instruction, which
4582	requires the function to be located in the same naturally aligned 256MB segment
4583	as the caller. The ``long_call`` and ``far`` attributes are synonyms and
4584	require the use of a different call sequence that works regardless
4585	of the distance between the functions.
4586
4587	These attributes have no effect for position-independent code.
4588
4589	These attributes take priority over command line switches such
4590	as ``-mlong-calls`` and ``-mno-long-calls``.)reST";
4591
4592	static const char AttrDoc_Mode[] = R"reST(No documentation.)reST";
4593
4594	static const char AttrDoc_ModularFormat[] = R"reST(The ``modular_format`` attribute can be applied to a function that bears the
4595	``format`` attribute (or standard library functions) to indicate that the
4596	implementation is "modular", that is, that the implementation is logically
4597	divided into a number of named aspects. When the compiler can determine that
4598	not all aspects of the implementation are needed for a given call, the compiler
4599	may redirect the call to the identifier given as the first argument to the
4600	attribute (the modular implementation function).
4601
4602	The second argument is an implementation name, and the remaining arguments are
4603	aspects of the format string for the compiler to report. The implementation
4604	name is an unevaluated identifier in the C namespace.
4605
4606	The compiler reports that a call requires an aspect by issuing a relocation for
4607	the symbol ``<impl_name>_<aspect>`` at the point of the call. This arranges for
4608	code and data needed to support the aspect of the implementation to be brought
4609	into the link to satisfy weak references in the modular implemenation function.
4610	If the compiler does not understand an aspect, it must summarily consider any
4611	call to require that aspect.
4612
4613	For example, say ``printf`` is annotated with
4614	``modular_format(__modular_printf, "__printf", "float")``. Then, a call to
4615	``printf(var, 42)`` would be untouched. A call to ``printf("%d", 42)`` would
4616	become a call to ``__modular_printf`` with the same arguments, as would
4617	``printf("%f", 42.0)``. The latter would be accompanied with a strong
4618	relocation against the symbol ``__printf_float``, which would bring floating
4619	point support for ``printf`` into the link.
4620
4621	If the attribute appears more than once on a declaration, or across a chain of
4622	redeclarations, it is an error for the attributes to have different arguments,
4623	excepting that the aspects may be in any order.
4624
4625	The following aspects are currently supported:
4626
4627	- ``float``: The call has a floating point argument)reST";
4628
4629	static const char AttrDoc_MustTail[] = R"reST(If a ``return`` statement is marked ``musttail``, this indicates that the
4630	compiler must generate a tail call for the program to be correct, even when
4631	optimizations are disabled. This guarantees that the call will not cause
4632	unbounded stack growth if it is part of a recursive cycle in the call graph.
4633
4634	If the callee is a virtual function that is implemented by a thunk, there is
4635	no guarantee in general that the thunk tail-calls the implementation of the
4636	virtual function, so such a call in a recursive cycle can still result in
4637	unbounded stack growth.
4638
4639	``clang::musttail`` can only be applied to a ``return`` statement whose value
4640	is the result of a function call (even functions returning void must use
4641	``return``, although no value is returned). The target function must have the
4642	same number of arguments as the caller. The types of the return value and all
4643	arguments must be similar according to C++ rules (differing only in cv
4644	qualifiers or array size), including the implicit "this" argument, if any.
4645	Any variables in scope, including all arguments to the function and the
4646	return value must be trivially destructible. The calling convention of the
4647	caller and callee must match, and they must not be variadic functions or have
4648	old style K&R C function declarations.
4649
4650	The lifetimes of all local variables and function parameters end immediately
4651	before the call to the function. This means that it is undefined behaviour to
4652	pass a pointer or reference to a local variable to the called function, which
4653	is not the case without the attribute. Clang will emit a warning in common
4654	cases where this happens.
4655
4656	``clang::musttail`` provides assurances that the tail call can be optimized on
4657	all targets, not just one.)reST";
4658
4659	static const char AttrDoc_NSConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4660	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4661	convention (e.g. functions starting with "get" are assumed to return at
4662	``+0``).
4663
4664	It can be overridden using a family of the following attributes. In
4665	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4666	a function communicates that the object is returned at ``+1``, and the caller
4667	is responsible for freeing it.
4668	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4669	specifies that the object is returned at ``+0`` and the ownership remains with
4670	the callee.
4671	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4672	the Objective-C method call consumes the reference to ``self``, e.g. by
4673	attaching it to a supplied parameter.
4674	Additionally, parameters can have an annotation
4675	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4676	as that parameter effectively transfers the ownership, and the caller is no
4677	longer responsible for it.
4678	These attributes affect code generation when interacting with ARC code, and
4679	they are used by the Clang Static Analyzer.
4680
4681	In C programs using CoreFoundation, a similar set of attributes:
4682	``__attribute__((cf_returns_not_retained))``,
4683	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4684	have the same respective semantics when applied to CoreFoundation objects.
4685	These attributes affect code generation when interacting with ARC code, and
4686	they are used by the Clang Static Analyzer.
4687
4688	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4689	the same attribute family is present:
4690	``__attribute__((os_returns_not_retained))``,
4691	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4692	with the same respective semantics.
4693	Similar to ``__attribute__((ns_consumes_self))``,
4694	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4695	the reference to "this" (e.g., when attaching it to a different object supplied
4696	as a parameter).
4697	Out parameters (parameters the function is meant to write into,
4698	either via pointers-to-pointers or references-to-pointers)
4699	may be annotated with ``__attribute__((os_returns_retained))``
4700	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4701	written into the out parameter should (or respectively should not) be released
4702	after use.
4703	Since often out parameters may or may not be written depending on the exit
4704	code of the function,
4705	annotations ``__attribute__((os_returns_retained_on_zero))``
4706	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4707	an out parameter at ``+1`` is written if and only if the function returns a zero
4708	(respectively non-zero) error code.
4709	Observe that return-code-dependent out parameter annotations are only
4710	available for retained out parameters, as non-retained object do not have to be
4711	released by the callee.
4712	These attributes are only used by the Clang Static Analyzer.
4713
4714	The family of attributes ``X_returns_X_retained`` can be added to functions,
4715	C++ methods, and Objective-C methods and properties.
4716	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4717	and Objective-C methods.)reST";
4718
4719	static const char AttrDoc_NSConsumesSelf[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4720	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4721	convention (e.g. functions starting with "get" are assumed to return at
4722	``+0``).
4723
4724	It can be overridden using a family of the following attributes. In
4725	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4726	a function communicates that the object is returned at ``+1``, and the caller
4727	is responsible for freeing it.
4728	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4729	specifies that the object is returned at ``+0`` and the ownership remains with
4730	the callee.
4731	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4732	the Objective-C method call consumes the reference to ``self``, e.g. by
4733	attaching it to a supplied parameter.
4734	Additionally, parameters can have an annotation
4735	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4736	as that parameter effectively transfers the ownership, and the caller is no
4737	longer responsible for it.
4738	These attributes affect code generation when interacting with ARC code, and
4739	they are used by the Clang Static Analyzer.
4740
4741	In C programs using CoreFoundation, a similar set of attributes:
4742	``__attribute__((cf_returns_not_retained))``,
4743	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4744	have the same respective semantics when applied to CoreFoundation objects.
4745	These attributes affect code generation when interacting with ARC code, and
4746	they are used by the Clang Static Analyzer.
4747
4748	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4749	the same attribute family is present:
4750	``__attribute__((os_returns_not_retained))``,
4751	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4752	with the same respective semantics.
4753	Similar to ``__attribute__((ns_consumes_self))``,
4754	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4755	the reference to "this" (e.g., when attaching it to a different object supplied
4756	as a parameter).
4757	Out parameters (parameters the function is meant to write into,
4758	either via pointers-to-pointers or references-to-pointers)
4759	may be annotated with ``__attribute__((os_returns_retained))``
4760	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4761	written into the out parameter should (or respectively should not) be released
4762	after use.
4763	Since often out parameters may or may not be written depending on the exit
4764	code of the function,
4765	annotations ``__attribute__((os_returns_retained_on_zero))``
4766	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4767	an out parameter at ``+1`` is written if and only if the function returns a zero
4768	(respectively non-zero) error code.
4769	Observe that return-code-dependent out parameter annotations are only
4770	available for retained out parameters, as non-retained object do not have to be
4771	released by the callee.
4772	These attributes are only used by the Clang Static Analyzer.
4773
4774	The family of attributes ``X_returns_X_retained`` can be added to functions,
4775	C++ methods, and Objective-C methods and properties.
4776	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4777	and Objective-C methods.)reST";
4778
4779	static const char AttrDoc_NSErrorDomain[] = R"reST(In Cocoa frameworks in Objective-C, one can group related error codes in enums
4780	and categorize these enums with error domains.
4781
4782	The ``ns_error_domain`` attribute indicates a global ``NSString`` or
4783	``CFString`` constant representing the error domain that an error code belongs
4784	to. For pointer uniqueness and code size this is a constant symbol, not a
4785	literal.
4786
4787	The domain and error code need to be used together. The ``ns_error_domain``
4788	attribute links error codes to their domain at the source level.
4789
4790	This metadata is useful for documentation purposes, for static analysis, and for
4791	improving interoperability between Objective-C and Swift. It is not used for
4792	code generation in Objective-C.
4793
4794	For example:
4795
4796	.. code-block:: objc
4797
4798	#define NS_ERROR_ENUM(_type, _name, _domain) \
4799	enum _name : _type _name; enum __attribute__((ns_error_domain(_domain))) _name : _type
4800
4801	extern NSString *const MyErrorDomain;
4802	typedef NS_ERROR_ENUM(unsigned char, MyErrorEnum, MyErrorDomain) {
4803	MyErrFirst,
4804	MyErrSecond,
4805	};)reST";
4806
4807	static const char AttrDoc_NSReturnsAutoreleased[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4808	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4809	convention (e.g. functions starting with "get" are assumed to return at
4810	``+0``).
4811
4812	It can be overridden using a family of the following attributes. In
4813	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4814	a function communicates that the object is returned at ``+1``, and the caller
4815	is responsible for freeing it.
4816	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4817	specifies that the object is returned at ``+0`` and the ownership remains with
4818	the callee.
4819	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4820	the Objective-C method call consumes the reference to ``self``, e.g. by
4821	attaching it to a supplied parameter.
4822	Additionally, parameters can have an annotation
4823	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4824	as that parameter effectively transfers the ownership, and the caller is no
4825	longer responsible for it.
4826	These attributes affect code generation when interacting with ARC code, and
4827	they are used by the Clang Static Analyzer.
4828
4829	In C programs using CoreFoundation, a similar set of attributes:
4830	``__attribute__((cf_returns_not_retained))``,
4831	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4832	have the same respective semantics when applied to CoreFoundation objects.
4833	These attributes affect code generation when interacting with ARC code, and
4834	they are used by the Clang Static Analyzer.
4835
4836	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4837	the same attribute family is present:
4838	``__attribute__((os_returns_not_retained))``,
4839	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4840	with the same respective semantics.
4841	Similar to ``__attribute__((ns_consumes_self))``,
4842	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4843	the reference to "this" (e.g., when attaching it to a different object supplied
4844	as a parameter).
4845	Out parameters (parameters the function is meant to write into,
4846	either via pointers-to-pointers or references-to-pointers)
4847	may be annotated with ``__attribute__((os_returns_retained))``
4848	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4849	written into the out parameter should (or respectively should not) be released
4850	after use.
4851	Since often out parameters may or may not be written depending on the exit
4852	code of the function,
4853	annotations ``__attribute__((os_returns_retained_on_zero))``
4854	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4855	an out parameter at ``+1`` is written if and only if the function returns a zero
4856	(respectively non-zero) error code.
4857	Observe that return-code-dependent out parameter annotations are only
4858	available for retained out parameters, as non-retained object do not have to be
4859	released by the callee.
4860	These attributes are only used by the Clang Static Analyzer.
4861
4862	The family of attributes ``X_returns_X_retained`` can be added to functions,
4863	C++ methods, and Objective-C methods and properties.
4864	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4865	and Objective-C methods.)reST";
4866
4867	static const char AttrDoc_NSReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4868	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4869	convention (e.g. functions starting with "get" are assumed to return at
4870	``+0``).
4871
4872	It can be overridden using a family of the following attributes. In
4873	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4874	a function communicates that the object is returned at ``+1``, and the caller
4875	is responsible for freeing it.
4876	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4877	specifies that the object is returned at ``+0`` and the ownership remains with
4878	the callee.
4879	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4880	the Objective-C method call consumes the reference to ``self``, e.g. by
4881	attaching it to a supplied parameter.
4882	Additionally, parameters can have an annotation
4883	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4884	as that parameter effectively transfers the ownership, and the caller is no
4885	longer responsible for it.
4886	These attributes affect code generation when interacting with ARC code, and
4887	they are used by the Clang Static Analyzer.
4888
4889	In C programs using CoreFoundation, a similar set of attributes:
4890	``__attribute__((cf_returns_not_retained))``,
4891	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4892	have the same respective semantics when applied to CoreFoundation objects.
4893	These attributes affect code generation when interacting with ARC code, and
4894	they are used by the Clang Static Analyzer.
4895
4896	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4897	the same attribute family is present:
4898	``__attribute__((os_returns_not_retained))``,
4899	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4900	with the same respective semantics.
4901	Similar to ``__attribute__((ns_consumes_self))``,
4902	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4903	the reference to "this" (e.g., when attaching it to a different object supplied
4904	as a parameter).
4905	Out parameters (parameters the function is meant to write into,
4906	either via pointers-to-pointers or references-to-pointers)
4907	may be annotated with ``__attribute__((os_returns_retained))``
4908	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4909	written into the out parameter should (or respectively should not) be released
4910	after use.
4911	Since often out parameters may or may not be written depending on the exit
4912	code of the function,
4913	annotations ``__attribute__((os_returns_retained_on_zero))``
4914	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4915	an out parameter at ``+1`` is written if and only if the function returns a zero
4916	(respectively non-zero) error code.
4917	Observe that return-code-dependent out parameter annotations are only
4918	available for retained out parameters, as non-retained object do not have to be
4919	released by the callee.
4920	These attributes are only used by the Clang Static Analyzer.
4921
4922	The family of attributes ``X_returns_X_retained`` can be added to functions,
4923	C++ methods, and Objective-C methods and properties.
4924	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4925	and Objective-C methods.)reST";
4926
4927	static const char AttrDoc_NSReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4928	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4929	convention (e.g. functions starting with "get" are assumed to return at
4930	``+0``).
4931
4932	It can be overridden using a family of the following attributes. In
4933	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4934	a function communicates that the object is returned at ``+1``, and the caller
4935	is responsible for freeing it.
4936	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4937	specifies that the object is returned at ``+0`` and the ownership remains with
4938	the callee.
4939	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4940	the Objective-C method call consumes the reference to ``self``, e.g. by
4941	attaching it to a supplied parameter.
4942	Additionally, parameters can have an annotation
4943	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4944	as that parameter effectively transfers the ownership, and the caller is no
4945	longer responsible for it.
4946	These attributes affect code generation when interacting with ARC code, and
4947	they are used by the Clang Static Analyzer.
4948
4949	In C programs using CoreFoundation, a similar set of attributes:
4950	``__attribute__((cf_returns_not_retained))``,
4951	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4952	have the same respective semantics when applied to CoreFoundation objects.
4953	These attributes affect code generation when interacting with ARC code, and
4954	they are used by the Clang Static Analyzer.
4955
4956	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4957	the same attribute family is present:
4958	``__attribute__((os_returns_not_retained))``,
4959	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4960	with the same respective semantics.
4961	Similar to ``__attribute__((ns_consumes_self))``,
4962	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4963	the reference to "this" (e.g., when attaching it to a different object supplied
4964	as a parameter).
4965	Out parameters (parameters the function is meant to write into,
4966	either via pointers-to-pointers or references-to-pointers)
4967	may be annotated with ``__attribute__((os_returns_retained))``
4968	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4969	written into the out parameter should (or respectively should not) be released
4970	after use.
4971	Since often out parameters may or may not be written depending on the exit
4972	code of the function,
4973	annotations ``__attribute__((os_returns_retained_on_zero))``
4974	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4975	an out parameter at ``+1`` is written if and only if the function returns a zero
4976	(respectively non-zero) error code.
4977	Observe that return-code-dependent out parameter annotations are only
4978	available for retained out parameters, as non-retained object do not have to be
4979	released by the callee.
4980	These attributes are only used by the Clang Static Analyzer.
4981
4982	The family of attributes ``X_returns_X_retained`` can be added to functions,
4983	C++ methods, and Objective-C methods and properties.
4984	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4985	and Objective-C methods.)reST";
4986
4987	static const char AttrDoc_Naked[] = R"reST(No documentation.)reST";
4988
4989	static const char AttrDoc_NoAlias[] = R"reST(The ``noalias`` attribute indicates that the only memory accesses inside
4990	function are loads and stores from objects pointed to by its pointer-typed
4991	arguments, with arbitrary offsets.)reST";
4992
4993	static const char AttrDoc_NoBuiltin[] = R"reST(The ``__attribute__((no_builtin))`` is similar to the ``-fno-builtin`` flag
4994	except it is specific to the body of a function. The attribute may also be
4995	applied to a virtual function but has no effect on the behavior of overriding
4996	functions in a derived class.
4997
4998	It accepts one or more strings corresponding to the specific names of the
4999	builtins to disable (e.g. "memcpy", "memset").
5000	If the attribute is used without parameters it will disable all buitins at
5001	once.
5002
5003	.. code-block:: c++
5004
5005	// The compiler is not allowed to add any builtin to foo's body.
5006	void foo(char* data, size_t count) __attribute__((no_builtin)) {
5007	// The compiler is not allowed to convert the loop into
5008	// `__builtin_memset(data, 0xFE, count);`.
5009	for (size_t i = 0; i < count; ++i)
5010	data[i] = 0xFE;
5011	}
5012
5013	// The compiler is not allowed to add the `memcpy` builtin to bar's body.
5014	void bar(char* data, size_t count) __attribute__((no_builtin("memcpy"))) {
5015	// The compiler is allowed to convert the loop into
5016	// `__builtin_memset(data, 0xFE, count);` but cannot generate any
5017	// `__builtin_memcpy`
5018	for (size_t i = 0; i < count; ++i)
5019	data[i] = 0xFE;
5020	})reST";
5021
5022	static const char AttrDoc_NoCommon[] = R"reST(No documentation.)reST";
5023
5024	static const char AttrDoc_NoConvergent[] = R"reST(This attribute prevents a function from being treated as convergent; when a
5025	function is marked ``noconvergent``, calls to that function are not
5026	automatically assumed to be convergent, unless such calls are explicitly marked
5027	as ``convergent``. If a statement is marked as ``noconvergent``, any calls to
5028	inline ``asm`` in that statement are no longer treated as convergent.
5029
5030	In languages following SPMD/SIMT programming model, e.g., CUDA/HIP, function
5031	declarations and inline asm calls are treated as convergent by default for
5032	correctness. This ``noconvergent`` attribute is helpful for developers to
5033	prevent them from being treated as convergent when it's safe.
5034
5035	.. code-block:: c
5036
5037	__device__ float bar(float);
5038	__device__ float foo(float) __attribute__((noconvergent)) {}
5039
5040	__device__ int example(void) {
5041	float x;
5042	[[clang::noconvergent]] x = bar(x); // no effect on convergence
5043	[[clang::noconvergent]] { asm volatile ("nop"); } // the asm call is non-convergent
5044	})reST";
5045
5046	static const char AttrDoc_NoDebug[] = R"reST(The ``nodebug`` attribute allows you to suppress debugging information for a
5047	function or method, for a variable that is not a parameter or a non-static
5048	data member, or for a typedef or using declaration.)reST";
5049
5050	static const char AttrDoc_NoDeref[] = R"reST(The ``noderef`` attribute causes clang to diagnose dereferences of annotated pointer types.
5051	This is ideally used with pointers that point to special memory which cannot be read
5052	from or written to, but allowing for the pointer to be used in pointer arithmetic.
5053	The following are examples of valid expressions where dereferences are diagnosed:
5054
5055	.. code-block:: c
5056
5057	int __attribute__((noderef)) *p;
5058	int x = *p; // warning
5059
5060	int __attribute__((noderef)) **p2;
5061	x = **p2; // warning
5062
5063	int * __attribute__((noderef)) *p3;
5064	p = *p3; // warning
5065
5066	struct S {
5067	int a;
5068	};
5069	struct S __attribute__((noderef)) *s;
5070	x = s->a; // warning
5071	x = (*s).a; // warning
5072
5073	Not all dereferences may diagnose a warning if the value directed by the pointer may not be
5074	accessed. The following are examples of valid expressions where may not be diagnosed:
5075
5076	.. code-block:: c
5077
5078	int *q;
5079	int __attribute__((noderef)) *p;
5080	q = &*p;
5081	q = *&p;
5082
5083	struct S {
5084	int a;
5085	};
5086	struct S __attribute__((noderef)) *s;
5087	p = &s->a;
5088	p = &(*s).a;
5089
5090	``noderef`` is currently only supported for pointers and arrays and not usable
5091	for references or Objective-C object pointers.
5092
5093	.. code-block:: c++
5094
5095	int x = 2;
5096	int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type
5097
5098	.. code-block:: objc
5099
5100	id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type)reST";
5101
5102	static const char AttrDoc_NoDestroy[] = R"reST(The ``no_destroy`` attribute specifies that a variable with static or thread
5103	storage duration shouldn't have its exit-time destructor run. Annotating every
5104	static and thread duration variable with this attribute is equivalent to
5105	invoking clang with -fno-c++-static-destructors.
5106
5107	If a variable is declared with this attribute, clang doesn't access check or
5108	generate the type's destructor. If you have a type that you only want to be
5109	annotated with ``no_destroy``, you can therefore declare the destructor private:
5110
5111	.. code-block:: c++
5112
5113	struct only_no_destroy {
5114	only_no_destroy();
5115	private:
5116	~only_no_destroy();
5117	};
5118
5119	[[clang::no_destroy]] only_no_destroy global; // fine!
5120
5121	Note that destructors are still required for subobjects of aggregates annotated
5122	with this attribute. This is because previously constructed subobjects need to
5123	be destroyed if an exception gets thrown before the initialization of the
5124	complete object is complete. For instance:
5125
5126	.. code-block:: c++
5127
5128	void f() {
5129	try {
5130	[[clang::no_destroy]]
5131	static only_no_destroy array[10]; // error, only_no_destroy has a private destructor.
5132	} catch (...) {
5133	// Handle the error
5134	}
5135	}
5136
5137	Here, if the construction of ``array[9]`` fails with an exception, ``array[0..8]``
5138	will be destroyed, so the element's destructor needs to be accessible.)reST";
5139
5140	static const char AttrDoc_NoDuplicate[] = R"reST(The ``noduplicate`` attribute can be placed on function declarations to control
5141	whether function calls to this function can be duplicated or not as a result of
5142	optimizations. This is required for the implementation of functions with
5143	certain special requirements, like the OpenCL "barrier" function, that might
5144	need to be run concurrently by all the threads that are executing in lockstep
5145	on the hardware. For example this attribute applied on the function
5146	"nodupfunc" in the code below avoids that:
5147
5148	.. code-block:: c
5149
5150	void nodupfunc() __attribute__((noduplicate));
5151	// Setting it as a C++11 attribute is also valid
5152	// void nodupfunc() [[clang::noduplicate]];
5153	void foo();
5154	void bar();
5155
5156	nodupfunc();
5157	if (a > n) {
5158	foo();
5159	} else {
5160	bar();
5161	}
5162
5163	gets possibly modified by some optimizations into code similar to this:
5164
5165	.. code-block:: c
5166
5167	if (a > n) {
5168	nodupfunc();
5169	foo();
5170	} else {
5171	nodupfunc();
5172	bar();
5173	}
5174
5175	where the call to "nodupfunc" is duplicated and sunk into the two branches
5176	of the condition.)reST";
5177
5178	static const char AttrDoc_NoEscape[] = R"reST(``noescape`` placed on a function parameter of a pointer type is used to inform
5179	the compiler that the pointer cannot escape: that is, no reference to the object
5180	the pointer points to that is derived from the parameter value will survive
5181	after the function returns. Users are responsible for making sure parameters
5182	annotated with ``noescape`` do not actually escape. Calling ``free()`` on such
5183	a parameter does not constitute an escape.
5184
5185	For example:
5186
5187	.. code-block:: c
5188
5189	int *gp;
5190
5191	void nonescapingFunc(__attribute__((noescape)) int *p) {
5192	*p += 100; // OK.
5193	}
5194
5195	void escapingFunc(__attribute__((noescape)) int *p) {
5196	gp = p; // Not OK.
5197	}
5198
5199	Additionally, when the parameter is a `block pointer
5200	<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
5201	applies to copies of the block. For example:
5202
5203	.. code-block:: c
5204
5205	typedef void (^BlockTy)();
5206	BlockTy g0, g1;
5207
5208	void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
5209	block(); // OK.
5210	}
5211
5212	void escapingFunc(__attribute__((noescape)) BlockTy block) {
5213	g0 = block; // Not OK.
5214	g1 = Block_copy(block); // Not OK either.
5215	})reST";
5216
5217	static const char AttrDoc_NoFieldProtection[] = R"reST(No documentation.)reST";
5218
5219	static const char AttrDoc_NoInline[] = R"reST(This function attribute suppresses the inlining of a function at the call sites
5220	of the function.
5221
5222	``[[clang::noinline]]`` spelling can be used as a statement attribute; other
5223	spellings of the attribute are not supported on statements. If a statement is
5224	marked ``[[clang::noinline]]`` and contains calls, those calls inside the
5225	statement will not be inlined by the compiler.
5226
5227	``__noinline__`` can be used as a keyword in CUDA/HIP languages. This is to
5228	avoid diagnostics due to usage of ``__attribute__((__noinline__))``
5229	with ``__noinline__`` defined as a macro as ``__attribute__((noinline))``.
5230
5231	.. code-block:: c
5232
5233	int example(void) {
5234	int r;
5235	[[clang::noinline]] foo();
5236	[[clang::noinline]] r = bar();
5237	return r;
5238	})reST";
5239
5240	static const char AttrDoc_NoInstrumentFunction[] = R"reST(No documentation.)reST";
5241
5242	static const char AttrDoc_NoMerge[] = R"reST(If a statement is marked ``nomerge`` and contains call expressions, those call
5243	expressions inside the statement will not be merged during optimization. This
5244	attribute can be used to prevent the optimizer from obscuring the source
5245	location of certain calls. For example, it will prevent tail merging otherwise
5246	identical code sequences that raise an exception or terminate the program. Tail
5247	merging normally reduces the precision of source location information, making
5248	stack traces less useful for debugging. This attribute gives the user control
5249	over the tradeoff between code size and debug information precision.
5250
5251	``nomerge`` attribute can also be used as function attribute to prevent all
5252	calls to the specified function from merging. It has no effect on indirect
5253	calls to such functions. For example:
5254
5255	.. code-block:: c++
5256
5257	[[clang::nomerge]] void foo(int) {}
5258
5259	void bar(int x) {
5260	auto *ptr = foo;
5261	if (x) foo(1); else foo(2); // will not be merged
5262	if (x) ptr(1); else ptr(2); // indirect call, can be merged
5263	}
5264
5265	``nomerge`` attribute can also be used for pointers to functions to
5266	prevent calls through such pointer from merging. In such case the
5267	effect applies only to a specific function pointer. For example:
5268
5269	.. code-block:: c++
5270
5271	[[clang::nomerge]] void (*foo)(int);
5272
5273	void bar(int x) {
5274	auto *ptr = foo;
5275	if (x) foo(1); else foo(2); // will not be merged
5276	if (x) ptr(1); else ptr(2); // 'ptr' has no 'nomerge' attribute, can be merged
5277	})reST";
5278
5279	static const char AttrDoc_NoMicroMips[] = R"reST(Clang supports the GNU style ``__attribute__((micromips))`` and
5280	``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
5281	may be attached to a function definition and instructs the backend to generate
5282	or not to generate microMIPS code for that function.
5283
5284	These attributes override the ``-mmicromips`` and ``-mno-micromips`` options
5285	on the command line.)reST";
5286
5287	static const char AttrDoc_NoMips16[] = R"reST(No documentation.)reST";
5288
5289	static const char AttrDoc_NoOutline[] = R"reST(This function attribute suppresses outlining from the annotated function.
5290
5291	Outlining is the process where common parts of separate functions are extracted
5292	into a separate function (or assembly snippet), and calls to that function or
5293	snippet are inserted in the original functions. In this way, it can be seen as
5294	the opposite of inlining. It can help to reduce code size.)reST";
5295
5296	static const char AttrDoc_NoProfileFunction[] = R"reST(Use the ``no_profile_instrument_function`` attribute on a function declaration
5297	to denote that the compiler should not instrument the function with
5298	profile-related instrumentation, such as via the
5299	``-fprofile-generate`` / ``-fprofile-instr-generate`` /
5300	``-fcs-profile-generate`` / ``-fprofile-arcs`` flags.)reST";
5301
5302	static const char AttrDoc_NoRandomizeLayout[] = R"reST(The attribute ``randomize_layout``, when attached to a C structure, selects it
5303	for structure layout field randomization; a compile-time hardening technique. A
5304	"seed" value, is specified via the ``-frandomize-layout-seed=`` command line flag.
5305	For example:
5306
5307	.. code-block:: bash
5308
5309	SEED=`od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n'`
5310	make ... CFLAGS="-frandomize-layout-seed=$SEED" ...
5311
5312	You can also supply the seed in a file with ``-frandomize-layout-seed-file=``.
5313	For example:
5314
5315	.. code-block:: bash
5316
5317	od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n' > /tmp/seed_file.txt
5318	make ... CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt" ...
5319
5320	The randomization is deterministic based for a given seed, so the entire
5321	program should be compiled with the same seed, but keep the seed safe
5322	otherwise.
5323
5324	The attribute ``no_randomize_layout``, when attached to a C structure,
5325	instructs the compiler that this structure should not have its field layout
5326	randomized.)reST";
5327
5328	static const char AttrDoc_NoReturn[] = R"reST(No documentation.)reST";
5329
5330	static const char AttrDoc_NoSanitize[] = R"reST(Use the ``no_sanitize`` attribute on a function or a global variable
5331	declaration to specify that a particular instrumentation or set of
5332	instrumentations should not be applied.
5333
5334	The attribute takes a list of string literals with the following accepted
5335	values:
5336
5337	* all values accepted by ``-fno-sanitize=``;
5338	* ``coverage``, to disable SanitizerCoverage instrumentation.
5339
5340	For example, ``__attribute__((no_sanitize("address", "thread")))`` specifies
5341	that AddressSanitizer and ThreadSanitizer should not be applied to the function
5342	or variable. Using ``__attribute__((no_sanitize("coverage")))`` specifies that
5343	SanitizerCoverage should not be applied to the function.
5344
5345	See :ref:`Controlling Code Generation <controlling-code-generation>` for a
5346	full list of supported sanitizer flags.)reST";
5347
5348	static const char AttrDoc_NoSpecializations[] = R"reST(``[[clang::no_specializations]]`` can be applied to function, class, or variable
5349	templates which should not be explicitly specialized by users. This is primarily
5350	used to diagnose user specializations of standard library type traits.)reST";
5351
5352	static const char AttrDoc_NoSpeculativeLoadHardening[] = R"reST(This attribute can be applied to a function declaration in order to indicate
5353	that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
5354	is not needed for the function body. This can also be applied to a method
5355	in Objective C. This attribute will take precedence over the command line flag in
5356	the case where `-mspeculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
5357
5358	Warning: This attribute may not prevent Speculative Load Hardening from being
5359	enabled for a function which inlines a function that has the
5360	'speculative_load_hardening' attribute. This is intended to provide a
5361	maximally conservative model where the code that is marked with the
5362	'speculative_load_hardening' attribute will always (even when inlined)
5363	be hardened. A user of this attribute may want to mark functions called by
5364	a function they do not want to be hardened with the 'noinline' attribute.
5365
5366	For example:
5367
5368	.. code-block:: c
5369
5370	__attribute__((speculative_load_hardening))
5371	int foo(int i) {
5372	return i;
5373	}
5374
5375	// Note: bar() may still have speculative load hardening enabled if
5376	// foo() is inlined into bar(). Mark foo() with __attribute__((noinline))
5377	// to avoid this situation.
5378	__attribute__((no_speculative_load_hardening))
5379	int bar(int i) {
5380	return foo(i);
5381	})reST";
5382
5383	static const char AttrDoc_NoSplitStack[] = R"reST(The ``no_split_stack`` attribute disables the emission of the split stack
5384	preamble for a particular function. It has no effect if ``-fsplit-stack``
5385	is not specified.)reST";
5386
5387	static const char AttrDoc_NoStackProtector[] = R"reST(Clang supports the GNU style ``__attribute__((no_stack_protector))`` and Microsoft
5388	style ``__declspec(safebuffers)`` attribute which disables
5389	the stack protector on the specified function. This attribute is useful for
5390	selectively disabling the stack protector on some functions when building with
5391	``-fstack-protector`` compiler option.
5392
5393	For example, it disables the stack protector for the function ``foo`` but function
5394	``bar`` will still be built with the stack protector with the ``-fstack-protector``
5395	option.
5396
5397	.. code-block:: c
5398
5399	int __attribute__((no_stack_protector))
5400	foo (int x); // stack protection will be disabled for foo.
5401
5402	int bar(int y); // bar can be built with the stack protector.)reST";
5403
5404	static const char AttrDoc_NoThreadSafetyAnalysis[] = R"reST(No documentation.)reST";
5405
5406	static const char AttrDoc_NoThrow[] = R"reST(Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
5407	``__declspec(nothrow)`` attribute as an equivalent of ``noexcept`` on function
5408	declarations. This attribute informs the compiler that the annotated function
5409	does not throw an exception. This prevents exception-unwinding. This attribute
5410	is particularly useful on functions in the C Standard Library that are
5411	guaranteed to not throw an exception.)reST";
5412
5413	static const char AttrDoc_NoTrivialAutoVarInit[] = R"reST(The ``__declspec(no_init_all)`` attribute disables the automatic initialization that the
5414	`-ftrivial-auto-var-init`_ flag would have applied to locals in a marked function, or instances of
5415	a marked type. Note that this attribute has no effect for locals that are automatically initialized
5416	without the `-ftrivial-auto-var-init`_ flag.
5417
5418	.. _`-ftrivial-auto-var-init`: ClangCommandLineReference.html#cmdoption-clang-ftrivial-auto-var-init)reST";
5419
5420	static const char AttrDoc_NoUniqueAddress[] = R"reST(The ``no_unique_address`` attribute allows tail padding in a non-static data
5421	member to overlap other members of the enclosing class (and in the special
5422	case when the type is empty, permits it to fully overlap other members).
5423	The field is laid out as if a base class were encountered at the corresponding
5424	point within the class (except that it does not share a vptr with the enclosing
5425	object).
5426
5427	Example usage:
5428
5429	.. code-block:: c++
5430
5431	template<typename T, typename Alloc> struct my_vector {
5432	T *p;
5433	[[no_unique_address]] Alloc alloc;
5434	// ...
5435	};
5436	static_assert(sizeof(my_vector<int, std::allocator<int>>) == sizeof(int*));
5437
5438	``[[no_unique_address]]`` is a standard C++20 attribute. Clang supports its use
5439	in C++11 onwards.
5440
5441	On MSVC targets, ``[[no_unique_address]]`` is ignored; use
5442	``[[msvc::no_unique_address]]`` instead. Currently there is no guarantee of ABI
5443	compatibility or stability with MSVC.)reST";
5444
5445	static const char AttrDoc_NoUwtable[] = R"reST(Clang supports the ``nouwtable`` attribute which skips emitting
5446	the unwind table entry for the specified function. This attribute is useful for
5447	selectively emitting the unwind table entry on some functions when building with
5448	``-funwind-tables`` compiler option.)reST";
5449
5450	static const char AttrDoc_NonAllocating[] = R"reST(Declares that a function or function type either does or does not allocate heap memory, according
5451	to the optional, compile-time constant boolean argument, which defaults to true. When the argument
5452	is false, the attribute is equivalent to ``allocating``.)reST";
5453
5454	static const char AttrDoc_NonBlocking[] = R"reST(Declares that a function or function type either does or does not block in any way, according
5455	to the optional, compile-time constant boolean argument, which defaults to true. When the argument
5456	is false, the attribute is equivalent to ``blocking``.
5457
5458	For the purposes of diagnostics, ``nonblocking`` is considered to include the
5459	``nonallocating`` guarantee and is therefore a "stronger" constraint or attribute.)reST";
5460
5461	static const char AttrDoc_NonNull[] = R"reST(The ``nonnull`` attribute indicates that some function parameters must not be
5462	null, and can be used in several different ways. It's original usage
5463	(`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_)
5464	is as a function (or Objective-C method) attribute that specifies which
5465	parameters of the function are nonnull in a comma-separated list. For example:
5466
5467	.. code-block:: c
5468
5469	extern void * my_memcpy (void dest, const void src, size_t len)
5470	__attribute__((nonnull (1, 2)));
5471
5472	Here, the ``nonnull`` attribute indicates that parameters 1 and 2
5473	cannot have a null value. Omitting the parenthesized list of parameter indices
5474	means that all parameters of pointer type cannot be null:
5475
5476	.. code-block:: c
5477
5478	extern void * my_memcpy (void dest, const void src, size_t len)
5479	__attribute__((nonnull));
5480
5481	Clang also allows the ``nonnull`` attribute to be placed directly on a function
5482	(or Objective-C method) parameter, eliminating the need to specify the
5483	parameter index ahead of type. For example:
5484
5485	.. code-block:: c
5486
5487	extern void * my_memcpy (void *dest __attribute__((nonnull)),
5488	const void *src __attribute__((nonnull)), size_t len);
5489
5490	Note that the ``nonnull`` attribute indicates that passing null to a non-null
5491	parameter is undefined behavior, which the optimizer may take advantage of to,
5492	e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a
5493	pointer cannot be null in a more general manner (because it is part of the type
5494	system) and does not imply undefined behavior, making it more widely applicable.)reST";
5495
5496	static const char AttrDoc_NonString[] = R"reST(The ``nonstring`` attribute can be applied to the declaration of a variable or
5497	a field whose type is a character pointer or character array to specify that
5498	the buffer is not intended to behave like a null-terminated string. This will
5499	silence diagnostics with code like:
5500
5501	.. code-block:: c
5502
5503	char BadStr[3] = "foo"; // No space for the null terminator, diagnosed
5504	__attribute__((nonstring)) char NotAStr[3] = "foo"; // Not diagnosed)reST";
5505
5506	static const char AttrDoc_NotTailCalled[] = R"reST(The ``not_tail_called`` attribute prevents tail-call optimization on statically
5507	bound calls. Objective-c methods, and functions marked as ``always_inline``
5508	cannot be marked as ``not_tail_called``.
5509
5510	For example, it prevents tail-call optimization in the following case:
5511
5512	.. code-block:: c
5513
5514	int __attribute__((not_tail_called)) foo1(int);
5515
5516	int foo2(int a) {
5517	return foo1(a); // No tail-call optimization on direct calls.
5518	}
5519
5520	However, it doesn't prevent tail-call optimization in this case:
5521
5522	.. code-block:: c
5523
5524	int __attribute__((not_tail_called)) foo1(int);
5525
5526	int foo2(int a) {
5527	int (*fn)(int) = &foo1;
5528
5529	// not_tail_called has no effect on an indirect call even if the call can
5530	// be resolved at compile time.
5531	return (*fn)(a);
5532	}
5533
5534	Generally, marking an overriding virtual function as ``not_tail_called`` is
5535	not useful, because this attribute is a property of the static type. Calls
5536	made through a pointer or reference to the base class type will respect
5537	the ``not_tail_called`` attribute of the base class's member function,
5538	regardless of the runtime destination of the call:
5539
5540	.. code-block:: c++
5541
5542	struct Foo { virtual void f(); };
5543	struct Bar : Foo {
5544	[[clang::not_tail_called]] void f() override;
5545	};
5546	void callera(Bar& bar) {
5547	Foo& foo = bar;
5548	// not_tail_called has no effect on here, even though the
5549	// underlying method is f from Bar.
5550	foo.f();
5551	bar.f(); // No tail-call optimization on here.
5552	})reST";
5553
5554	static const char AttrDoc_OMPAllocateDecl[] = R"reST()reST";
5555
5556	static const char AttrDoc_OMPAssume[] = R"reST(Clang supports the ``[[omp::assume("assumption")]]`` attribute to
5557	provide additional information to the optimizer. The string-literal, here
5558	"assumption", will be attached to the function declaration such that later
5559	analysis and optimization passes can assume the "assumption" to hold.
5560	This is similar to :ref:`__builtin_assume <langext-__builtin_assume>` but
5561	instead of an expression that can be assumed to be non-zero, the assumption is
5562	expressed as a string and it holds for the entire function.
5563
5564	A function can have multiple assume attributes and they propagate from prior
5565	declarations to later definitions. Multiple assumptions are aggregated into a
5566	single comma separated string. Thus, one can provide multiple assumptions via
5567	a comma separated string, i.a.,
5568	``[[omp::assume("assumption1,assumption2")]]``.
5569
5570	While LLVM plugins might provide more assumption strings, the default LLVM
5571	optimization passes are aware of the following assumptions:
5572
5573	.. code-block:: none
5574
5575	"omp_no_openmp"
5576	"omp_no_openmp_routines"
5577	"omp_no_parallelism"
5578	"omp_no_openmp_constructs"
5579
5580	The OpenMP standard defines the meaning of OpenMP assumptions ("omp_XYZ" is
5581	spelled "XYZ" in the `OpenMP 5.1 Standard`_).
5582
5583	.. _`OpenMP 5.1 Standard`: https://www.openmp.org/spec-html/5.1/openmpsu37.html#x56-560002.5.2)reST";
5584
5585	static const char AttrDoc_OMPCaptureKind[] = R"reST()reST";
5586
5587	static const char AttrDoc_OMPCaptureNoInit[] = R"reST()reST";
5588
5589	static const char AttrDoc_OMPDeclareSimdDecl[] = R"reST(The ``declare simd`` construct can be applied to a function to enable the creation
5590	of one or more versions that can process multiple arguments using SIMD
5591	instructions from a single invocation in a SIMD loop. The ``declare simd``
5592	directive is a declarative directive. There may be multiple ``declare simd``
5593	directives for a function. The use of a ``declare simd`` construct on a function
5594	enables the creation of SIMD versions of the associated function that can be
5595	used to process multiple arguments from a single invocation from a SIMD loop
5596	concurrently.
5597	The syntax of the ``declare simd`` construct is as follows:
5598
5599	.. code-block:: none
5600
5601	#pragma omp declare simd [clause[[,] clause] ...] new-line
5602	[#pragma omp declare simd [clause[[,] clause] ...] new-line]
5603	[...]
5604	function definition or declaration
5605
5606	where clause is one of the following:
5607
5608	.. code-block:: none
5609
5610	simdlen(length)
5611	linear(argument-list[:constant-linear-step])
5612	aligned(argument-list[:alignment])
5613	uniform(argument-list)
5614	inbranch
5615	notinbranch)reST";
5616
5617	static const char AttrDoc_OMPDeclareTargetDecl[] = R"reST(The ``declare target`` directive specifies that variables and functions are mapped
5618	to a device for OpenMP offload mechanism.
5619
5620	The syntax of the declare target directive is as follows:
5621
5622	.. code-block:: c
5623
5624	#pragma omp declare target new-line
5625	declarations-definition-seq
5626	#pragma omp end declare target new-line
5627
5628	or
5629
5630	.. code-block:: c
5631
5632	#pragma omp declare target (extended-list) new-line
5633
5634	or
5635
5636	.. code-block:: c
5637
5638	#pragma omp declare target clause[ [,] clause ... ] new-line
5639
5640	where clause is one of the following:
5641
5642
5643	.. code-block:: c
5644
5645	to(extended-list)
5646	link(list)
5647	device_type(host \| nohost \| any))reST";
5648
5649	static const char AttrDoc_OMPDeclareVariant[] = R"reST(The ``declare variant`` directive declares a specialized variant of a base
5650	function and specifies the context in which that specialized variant is used.
5651	The declare variant directive is a declarative directive.
5652	The syntax of the ``declare variant`` construct is as follows:
5653
5654	.. code-block:: none
5655
5656	#pragma omp declare variant(variant-func-id) clause new-line
5657	[#pragma omp declare variant(variant-func-id) clause new-line]
5658	[...]
5659	function definition or declaration
5660
5661	where clause is one of the following:
5662
5663	.. code-block:: none
5664
5665	match(context-selector-specification)
5666
5667	and where ``variant-func-id`` is the name of a function variant that is either a
5668	base language identifier or, for C++, a template-id.
5669
5670	Clang provides the following context selector extensions, used via
5671	``implementation={extension(EXTENSION)}``:
5672
5673	.. code-block:: none
5674
5675	match_all
5676	match_any
5677	match_none
5678	disable_implicit_base
5679	allow_templates
5680	bind_to_declaration
5681
5682	The match extensions change when the entire context selector is considered a
5683	match for an OpenMP context. The default is ``all``, with ``none`` no trait in the
5684	selector is allowed to be in the OpenMP context, with ``any`` a single trait in
5685	both the selector and OpenMP context is sufficient. Only a single match
5686	extension trait is allowed per context selector.
5687	The disable extensions remove default effects of the ``begin declare variant``
5688	applied to a definition. If ``disable_implicit_base`` is given, we will not
5689	introduce an implicit base function for a variant if no base function was
5690	found. The variant is still generated but will never be called, due to the
5691	absence of a base function and consequently calls to a base function.
5692	The allow extensions change when the ``begin declare variant`` effect is
5693	applied to a definition. If ``allow_templates`` is given, template function
5694	definitions are considered as specializations of existing or assumed template
5695	declarations with the same name. The template parameters for the base functions
5696	are used to instantiate the specialization. If ``bind_to_declaration`` is given,
5697	apply the same variant rules to function declarations. This allows the user to
5698	override declarations with only a function declaration.)reST";
5699
5700	static const char AttrDoc_OMPGroupPrivateDecl[] = R"reST()reST";
5701
5702	static const char AttrDoc_OMPReferencedVar[] = R"reST()reST";
5703
5704	static const char AttrDoc_OMPTargetIndirectCall[] = R"reST()reST";
5705
5706	static const char AttrDoc_OMPThreadPrivateDecl[] = R"reST()reST";
5707
5708	static const char AttrDoc_OSConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5709	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5710	convention (e.g. functions starting with "get" are assumed to return at
5711	``+0``).
5712
5713	It can be overridden using a family of the following attributes. In
5714	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5715	a function communicates that the object is returned at ``+1``, and the caller
5716	is responsible for freeing it.
5717	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5718	specifies that the object is returned at ``+0`` and the ownership remains with
5719	the callee.
5720	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5721	the Objective-C method call consumes the reference to ``self``, e.g. by
5722	attaching it to a supplied parameter.
5723	Additionally, parameters can have an annotation
5724	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5725	as that parameter effectively transfers the ownership, and the caller is no
5726	longer responsible for it.
5727	These attributes affect code generation when interacting with ARC code, and
5728	they are used by the Clang Static Analyzer.
5729
5730	In C programs using CoreFoundation, a similar set of attributes:
5731	``__attribute__((cf_returns_not_retained))``,
5732	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5733	have the same respective semantics when applied to CoreFoundation objects.
5734	These attributes affect code generation when interacting with ARC code, and
5735	they are used by the Clang Static Analyzer.
5736
5737	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5738	the same attribute family is present:
5739	``__attribute__((os_returns_not_retained))``,
5740	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5741	with the same respective semantics.
5742	Similar to ``__attribute__((ns_consumes_self))``,
5743	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5744	the reference to "this" (e.g., when attaching it to a different object supplied
5745	as a parameter).
5746	Out parameters (parameters the function is meant to write into,
5747	either via pointers-to-pointers or references-to-pointers)
5748	may be annotated with ``__attribute__((os_returns_retained))``
5749	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5750	written into the out parameter should (or respectively should not) be released
5751	after use.
5752	Since often out parameters may or may not be written depending on the exit
5753	code of the function,
5754	annotations ``__attribute__((os_returns_retained_on_zero))``
5755	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5756	an out parameter at ``+1`` is written if and only if the function returns a zero
5757	(respectively non-zero) error code.
5758	Observe that return-code-dependent out parameter annotations are only
5759	available for retained out parameters, as non-retained object do not have to be
5760	released by the callee.
5761	These attributes are only used by the Clang Static Analyzer.
5762
5763	The family of attributes ``X_returns_X_retained`` can be added to functions,
5764	C++ methods, and Objective-C methods and properties.
5765	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5766	and Objective-C methods.)reST";
5767
5768	static const char AttrDoc_OSConsumesThis[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5769	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5770	convention (e.g. functions starting with "get" are assumed to return at
5771	``+0``).
5772
5773	It can be overridden using a family of the following attributes. In
5774	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5775	a function communicates that the object is returned at ``+1``, and the caller
5776	is responsible for freeing it.
5777	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5778	specifies that the object is returned at ``+0`` and the ownership remains with
5779	the callee.
5780	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5781	the Objective-C method call consumes the reference to ``self``, e.g. by
5782	attaching it to a supplied parameter.
5783	Additionally, parameters can have an annotation
5784	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5785	as that parameter effectively transfers the ownership, and the caller is no
5786	longer responsible for it.
5787	These attributes affect code generation when interacting with ARC code, and
5788	they are used by the Clang Static Analyzer.
5789
5790	In C programs using CoreFoundation, a similar set of attributes:
5791	``__attribute__((cf_returns_not_retained))``,
5792	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5793	have the same respective semantics when applied to CoreFoundation objects.
5794	These attributes affect code generation when interacting with ARC code, and
5795	they are used by the Clang Static Analyzer.
5796
5797	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5798	the same attribute family is present:
5799	``__attribute__((os_returns_not_retained))``,
5800	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5801	with the same respective semantics.
5802	Similar to ``__attribute__((ns_consumes_self))``,
5803	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5804	the reference to "this" (e.g., when attaching it to a different object supplied
5805	as a parameter).
5806	Out parameters (parameters the function is meant to write into,
5807	either via pointers-to-pointers or references-to-pointers)
5808	may be annotated with ``__attribute__((os_returns_retained))``
5809	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5810	written into the out parameter should (or respectively should not) be released
5811	after use.
5812	Since often out parameters may or may not be written depending on the exit
5813	code of the function,
5814	annotations ``__attribute__((os_returns_retained_on_zero))``
5815	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5816	an out parameter at ``+1`` is written if and only if the function returns a zero
5817	(respectively non-zero) error code.
5818	Observe that return-code-dependent out parameter annotations are only
5819	available for retained out parameters, as non-retained object do not have to be
5820	released by the callee.
5821	These attributes are only used by the Clang Static Analyzer.
5822
5823	The family of attributes ``X_returns_X_retained`` can be added to functions,
5824	C++ methods, and Objective-C methods and properties.
5825	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5826	and Objective-C methods.)reST";
5827
5828	static const char AttrDoc_OSReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5829	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5830	convention (e.g. functions starting with "get" are assumed to return at
5831	``+0``).
5832
5833	It can be overridden using a family of the following attributes. In
5834	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5835	a function communicates that the object is returned at ``+1``, and the caller
5836	is responsible for freeing it.
5837	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5838	specifies that the object is returned at ``+0`` and the ownership remains with
5839	the callee.
5840	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5841	the Objective-C method call consumes the reference to ``self``, e.g. by
5842	attaching it to a supplied parameter.
5843	Additionally, parameters can have an annotation
5844	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5845	as that parameter effectively transfers the ownership, and the caller is no
5846	longer responsible for it.
5847	These attributes affect code generation when interacting with ARC code, and
5848	they are used by the Clang Static Analyzer.
5849
5850	In C programs using CoreFoundation, a similar set of attributes:
5851	``__attribute__((cf_returns_not_retained))``,
5852	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5853	have the same respective semantics when applied to CoreFoundation objects.
5854	These attributes affect code generation when interacting with ARC code, and
5855	they are used by the Clang Static Analyzer.
5856
5857	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5858	the same attribute family is present:
5859	``__attribute__((os_returns_not_retained))``,
5860	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5861	with the same respective semantics.
5862	Similar to ``__attribute__((ns_consumes_self))``,
5863	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5864	the reference to "this" (e.g., when attaching it to a different object supplied
5865	as a parameter).
5866	Out parameters (parameters the function is meant to write into,
5867	either via pointers-to-pointers or references-to-pointers)
5868	may be annotated with ``__attribute__((os_returns_retained))``
5869	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5870	written into the out parameter should (or respectively should not) be released
5871	after use.
5872	Since often out parameters may or may not be written depending on the exit
5873	code of the function,
5874	annotations ``__attribute__((os_returns_retained_on_zero))``
5875	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5876	an out parameter at ``+1`` is written if and only if the function returns a zero
5877	(respectively non-zero) error code.
5878	Observe that return-code-dependent out parameter annotations are only
5879	available for retained out parameters, as non-retained object do not have to be
5880	released by the callee.
5881	These attributes are only used by the Clang Static Analyzer.
5882
5883	The family of attributes ``X_returns_X_retained`` can be added to functions,
5884	C++ methods, and Objective-C methods and properties.
5885	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5886	and Objective-C methods.)reST";
5887
5888	static const char AttrDoc_OSReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5889	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5890	convention (e.g. functions starting with "get" are assumed to return at
5891	``+0``).
5892
5893	It can be overridden using a family of the following attributes. In
5894	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5895	a function communicates that the object is returned at ``+1``, and the caller
5896	is responsible for freeing it.
5897	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5898	specifies that the object is returned at ``+0`` and the ownership remains with
5899	the callee.
5900	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5901	the Objective-C method call consumes the reference to ``self``, e.g. by
5902	attaching it to a supplied parameter.
5903	Additionally, parameters can have an annotation
5904	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5905	as that parameter effectively transfers the ownership, and the caller is no
5906	longer responsible for it.
5907	These attributes affect code generation when interacting with ARC code, and
5908	they are used by the Clang Static Analyzer.
5909
5910	In C programs using CoreFoundation, a similar set of attributes:
5911	``__attribute__((cf_returns_not_retained))``,
5912	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5913	have the same respective semantics when applied to CoreFoundation objects.
5914	These attributes affect code generation when interacting with ARC code, and
5915	they are used by the Clang Static Analyzer.
5916
5917	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5918	the same attribute family is present:
5919	``__attribute__((os_returns_not_retained))``,
5920	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5921	with the same respective semantics.
5922	Similar to ``__attribute__((ns_consumes_self))``,
5923	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5924	the reference to "this" (e.g., when attaching it to a different object supplied
5925	as a parameter).
5926	Out parameters (parameters the function is meant to write into,
5927	either via pointers-to-pointers or references-to-pointers)
5928	may be annotated with ``__attribute__((os_returns_retained))``
5929	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5930	written into the out parameter should (or respectively should not) be released
5931	after use.
5932	Since often out parameters may or may not be written depending on the exit
5933	code of the function,
5934	annotations ``__attribute__((os_returns_retained_on_zero))``
5935	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5936	an out parameter at ``+1`` is written if and only if the function returns a zero
5937	(respectively non-zero) error code.
5938	Observe that return-code-dependent out parameter annotations are only
5939	available for retained out parameters, as non-retained object do not have to be
5940	released by the callee.
5941	These attributes are only used by the Clang Static Analyzer.
5942
5943	The family of attributes ``X_returns_X_retained`` can be added to functions,
5944	C++ methods, and Objective-C methods and properties.
5945	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5946	and Objective-C methods.)reST";
5947
5948	static const char AttrDoc_OSReturnsRetainedOnNonZero[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5949	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5950	convention (e.g. functions starting with "get" are assumed to return at
5951	``+0``).
5952
5953	It can be overridden using a family of the following attributes. In
5954	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5955	a function communicates that the object is returned at ``+1``, and the caller
5956	is responsible for freeing it.
5957	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5958	specifies that the object is returned at ``+0`` and the ownership remains with
5959	the callee.
5960	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5961	the Objective-C method call consumes the reference to ``self``, e.g. by
5962	attaching it to a supplied parameter.
5963	Additionally, parameters can have an annotation
5964	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5965	as that parameter effectively transfers the ownership, and the caller is no
5966	longer responsible for it.
5967	These attributes affect code generation when interacting with ARC code, and
5968	they are used by the Clang Static Analyzer.
5969
5970	In C programs using CoreFoundation, a similar set of attributes:
5971	``__attribute__((cf_returns_not_retained))``,
5972	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5973	have the same respective semantics when applied to CoreFoundation objects.
5974	These attributes affect code generation when interacting with ARC code, and
5975	they are used by the Clang Static Analyzer.
5976
5977	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5978	the same attribute family is present:
5979	``__attribute__((os_returns_not_retained))``,
5980	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5981	with the same respective semantics.
5982	Similar to ``__attribute__((ns_consumes_self))``,
5983	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5984	the reference to "this" (e.g., when attaching it to a different object supplied
5985	as a parameter).
5986	Out parameters (parameters the function is meant to write into,
5987	either via pointers-to-pointers or references-to-pointers)
5988	may be annotated with ``__attribute__((os_returns_retained))``
5989	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5990	written into the out parameter should (or respectively should not) be released
5991	after use.
5992	Since often out parameters may or may not be written depending on the exit
5993	code of the function,
5994	annotations ``__attribute__((os_returns_retained_on_zero))``
5995	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5996	an out parameter at ``+1`` is written if and only if the function returns a zero
5997	(respectively non-zero) error code.
5998	Observe that return-code-dependent out parameter annotations are only
5999	available for retained out parameters, as non-retained object do not have to be
6000	released by the callee.
6001	These attributes are only used by the Clang Static Analyzer.
6002
6003	The family of attributes ``X_returns_X_retained`` can be added to functions,
6004	C++ methods, and Objective-C methods and properties.
6005	Attributes ``X_consumed`` can be added to parameters of methods, functions,
6006	and Objective-C methods.)reST";
6007
6008	static const char AttrDoc_OSReturnsRetainedOnZero[] = R"reST(The behavior of a function with respect to reference counting for Foundation
6009	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
6010	convention (e.g. functions starting with "get" are assumed to return at
6011	``+0``).
6012
6013	It can be overridden using a family of the following attributes. In
6014	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
6015	a function communicates that the object is returned at ``+1``, and the caller
6016	is responsible for freeing it.
6017	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
6018	specifies that the object is returned at ``+0`` and the ownership remains with
6019	the callee.
6020	The annotation ``__attribute__((ns_consumes_self))`` specifies that
6021	the Objective-C method call consumes the reference to ``self``, e.g. by
6022	attaching it to a supplied parameter.
6023	Additionally, parameters can have an annotation
6024	``__attribute__((ns_consumed))``, which specifies that passing an owned object
6025	as that parameter effectively transfers the ownership, and the caller is no
6026	longer responsible for it.
6027	These attributes affect code generation when interacting with ARC code, and
6028	they are used by the Clang Static Analyzer.
6029
6030	In C programs using CoreFoundation, a similar set of attributes:
6031	``__attribute__((cf_returns_not_retained))``,
6032	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
6033	have the same respective semantics when applied to CoreFoundation objects.
6034	These attributes affect code generation when interacting with ARC code, and
6035	they are used by the Clang Static Analyzer.
6036
6037	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
6038	the same attribute family is present:
6039	``__attribute__((os_returns_not_retained))``,
6040	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
6041	with the same respective semantics.
6042	Similar to ``__attribute__((ns_consumes_self))``,
6043	``__attribute__((os_consumes_this))`` specifies that the method call consumes
6044	the reference to "this" (e.g., when attaching it to a different object supplied
6045	as a parameter).
6046	Out parameters (parameters the function is meant to write into,
6047	either via pointers-to-pointers or references-to-pointers)
6048	may be annotated with ``__attribute__((os_returns_retained))``
6049	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
6050	written into the out parameter should (or respectively should not) be released
6051	after use.
6052	Since often out parameters may or may not be written depending on the exit
6053	code of the function,
6054	annotations ``__attribute__((os_returns_retained_on_zero))``
6055	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
6056	an out parameter at ``+1`` is written if and only if the function returns a zero
6057	(respectively non-zero) error code.
6058	Observe that return-code-dependent out parameter annotations are only
6059	available for retained out parameters, as non-retained object do not have to be
6060	released by the callee.
6061	These attributes are only used by the Clang Static Analyzer.
6062
6063	The family of attributes ``X_returns_X_retained`` can be added to functions,
6064	C++ methods, and Objective-C methods and properties.
6065	Attributes ``X_consumed`` can be added to parameters of methods, functions,
6066	and Objective-C methods.)reST";
6067
6068	static const char AttrDoc_ObjCBoxable[] = R"reST(Structs and unions marked with the ``objc_boxable`` attribute can be used
6069	with the Objective-C boxed expression syntax, ``@(...)``.
6070
6071	Usage: ``__attribute__((objc_boxable))``. This attribute
6072	can only be placed on a declaration of a trivially-copyable struct or union:
6073
6074	.. code-block:: objc
6075
6076	struct __attribute__((objc_boxable)) some_struct {
6077	int i;
6078	};
6079	union __attribute__((objc_boxable)) some_union {
6080	int i;
6081	float f;
6082	};
6083	typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
6084
6085	// ...
6086
6087	some_struct ss;
6088	NSValue *boxed = @(ss);)reST";
6089
6090	static const char AttrDoc_ObjCBridge[] = R"reST(No documentation.)reST";
6091
6092	static const char AttrDoc_ObjCBridgeMutable[] = R"reST(No documentation.)reST";
6093
6094	static const char AttrDoc_ObjCBridgeRelated[] = R"reST(No documentation.)reST";
6095
6096	static const char AttrDoc_ObjCClassStub[] = R"reST(This attribute specifies that the Objective-C class to which it applies is
6097	instantiated at runtime.
6098
6099	Unlike ``__attribute__((objc_runtime_visible))``, a class having this attribute
6100	still has a "class stub" that is visible to the linker. This allows categories
6101	to be defined. Static message sends with the class as a receiver use a special
6102	access pattern to ensure the class is lazily instantiated from the class stub.
6103
6104	Classes annotated with this attribute cannot be subclassed and cannot have
6105	implementations defined for them. This attribute is intended for use in
6106	Swift-generated headers for classes defined in Swift.
6107
6108	Adding or removing this attribute to a class is an ABI-breaking change.)reST";
6109
6110	static const char AttrDoc_ObjCDesignatedInitializer[] = R"reST(No documentation.)reST";
6111
6112	static const char AttrDoc_ObjCDirect[] = R"reST(The ``objc_direct`` attribute can be used to mark an Objective-C method as
6113	being direct. A direct method is treated statically like an ordinary method,
6114	but dynamically it behaves more like a C function. This lowers some of the costs
6115	associated with the method but also sacrifices some of the ordinary capabilities
6116	of Objective-C methods.
6117
6118	A message send of a direct method calls the implementation directly, as if it
6119	were a C function, rather than using ordinary Objective-C method dispatch. This
6120	is substantially faster and potentially allows the implementation to be inlined,
6121	but it also means the method cannot be overridden in subclasses or replaced
6122	dynamically, as ordinary Objective-C methods can.
6123
6124	Furthermore, a direct method is not listed in the class's method lists. This
6125	substantially reduces the code-size overhead of the method but also means it
6126	cannot be called dynamically using ordinary Objective-C method dispatch at all;
6127	in particular, this means that it cannot override a superclass method or satisfy
6128	a protocol requirement.
6129
6130	Because a direct method cannot be overridden, it is an error to perform
6131	a ``super`` message send of one.
6132
6133	Although a message send of a direct method causes the method to be called
6134	directly as if it were a C function, it still obeys Objective-C semantics in other
6135	ways:
6136
6137	- If the receiver is ``nil``, the message send does nothing and returns the zero value
6138	for the return type.
6139
6140	- A message send of a direct class method will cause the class to be initialized,
6141	including calling the ``+initialize`` method if present.
6142
6143	- The implicit ``_cmd`` parameter containing the method's selector is still defined.
6144	In order to minimize code-size costs, the implementation will not emit a reference
6145	to the selector if the parameter is unused within the method.
6146
6147	Symbols for direct method implementations are implicitly given hidden
6148	visibility, meaning that they can only be called within the same linkage unit.
6149
6150	It is an error to do any of the following:
6151
6152	- declare a direct method in a protocol,
6153	- declare an override of a direct method with a method in a subclass,
6154	- declare an override of a non-direct method with a direct method in a subclass,
6155	- declare a method with different directness in different class interfaces, or
6156	- implement a non-direct method (as declared in any class interface) with a direct method.
6157
6158	If any of these rules would be violated if every method defined in an
6159	``@implementation`` within a single linkage unit were declared in an
6160	appropriate class interface, the program is ill-formed with no diagnostic
6161	required. If a violation of this rule is not diagnosed, behavior remains
6162	well-defined; this paragraph is simply reserving the right to diagnose such
6163	conflicts in the future, not to treat them as undefined behavior.
6164
6165	Additionally, Clang will warn about any ``@selector`` expression that
6166	names a selector that is only known to be used for direct methods.
6167
6168	For the purpose of these rules, a "class interface" includes a class's primary
6169	``@interface`` block, its class extensions, its categories, its declared protocols,
6170	and all the class interfaces of its superclasses.
6171
6172	An Objective-C property can be declared with the ``direct`` property
6173	attribute. If a direct property declaration causes an implicit declaration of
6174	a getter or setter method (that is, if the given method is not explicitly
6175	declared elsewhere), the method is declared to be direct.
6176
6177	Some programmers may wish to make many methods direct at once. In order
6178	to simplify this, the ``objc_direct_members`` attribute is provided; see its
6179	documentation for more information.)reST";
6180
6181	static const char AttrDoc_ObjCDirectMembers[] = R"reST(The ``objc_direct_members`` attribute can be placed on an Objective-C
6182	``@interface`` or ``@implementation`` to mark that methods declared
6183	therein should be considered direct by default. See the documentation
6184	for ``objc_direct`` for more information about direct methods.
6185
6186	When ``objc_direct_members`` is placed on an ``@interface`` block, every
6187	method in the block is considered to be declared as direct. This includes any
6188	implicit method declarations introduced by property declarations. If the method
6189	redeclares a non-direct method, the declaration is ill-formed, exactly as if the
6190	method was annotated with the ``objc_direct`` attribute.
6191
6192	When ``objc_direct_members`` is placed on an ``@implementation`` block,
6193	methods defined in the block are considered to be declared as direct unless
6194	they have been previously declared as non-direct in any interface of the class.
6195	This includes the implicit method definitions introduced by synthesized
6196	properties, including auto-synthesized properties.)reST";
6197
6198	static const char AttrDoc_ObjCException[] = R"reST(No documentation.)reST";
6199
6200	static const char AttrDoc_ObjCExplicitProtocolImpl[] = R"reST(No documentation.)reST";
6201
6202	static const char AttrDoc_ObjCExternallyRetained[] = R"reST(The ``objc_externally_retained`` attribute can be applied to strong local
6203	variables, functions, methods, or blocks to opt into
6204	`externally-retained semantics
6205	<https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables>`_.
6206
6207	When applied to the definition of a function, method, or block, every parameter
6208	of the function with implicit strong retainable object pointer type is
6209	considered externally-retained, and becomes ``const``. By explicitly annotating
6210	a parameter with ``__strong``, you can opt back into the default
6211	non-externally-retained behavior for that parameter. For instance,
6212	``first_param`` is externally-retained below, but not ``second_param``:
6213
6214	.. code-block:: objc
6215
6216	__attribute__((objc_externally_retained))
6217	void f(NSArray first_param, __strong NSArray second_param) {
6218	// ...
6219	}
6220
6221	Likewise, when applied to a strong local variable, that variable becomes
6222	``const`` and is considered externally-retained.
6223
6224	When compiled without ``-fobjc-arc``, this attribute is ignored.)reST";
6225
6226	static const char AttrDoc_ObjCGC[] = R"reST(No documentation.)reST";
6227
6228	static const char AttrDoc_ObjCIndependentClass[] = R"reST(No documentation.)reST";
6229
6230	static const char AttrDoc_ObjCInertUnsafeUnretained[] = R"reST()reST";
6231
6232	static const char AttrDoc_ObjCKindOf[] = R"reST(No documentation.)reST";
6233
6234	static const char AttrDoc_ObjCMethodFamily[] = R"reST(Many methods in Objective-C have conventional meanings determined by their
6235	selectors. It is sometimes useful to be able to mark a method as having a
6236	particular conventional meaning despite not having the right selector, or as
6237	not having the conventional meaning that its selector would suggest. For these
6238	use cases, we provide an attribute to specifically describe the "method family"
6239	that a method belongs to.
6240
6241	Usage: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
6242	``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
6243	attribute can only be placed at the end of a method declaration:
6244
6245	.. code-block:: objc
6246
6247	- (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
6248
6249	Users who do not wish to change the conventional meaning of a method, and who
6250	merely want to document its non-standard retain and release semantics, should
6251	use the retaining behavior attributes (``ns_returns_retained``,
6252	``ns_returns_not_retained``, etc).
6253
6254	Query for this feature with ``__has_attribute(objc_method_family)``.)reST";
6255
6256	static const char AttrDoc_ObjCNSObject[] = R"reST(No documentation.)reST";
6257
6258	static const char AttrDoc_ObjCNonLazyClass[] = R"reST(This attribute can be added to an Objective-C ``@interface`` or
6259	``@implementation`` declaration to add the class to the list of non-lazily
6260	initialized classes. A non-lazy class will be initialized eagerly when the
6261	Objective-C runtime is loaded. This is required for certain system classes which
6262	have instances allocated in non-standard ways, such as the classes for blocks
6263	and constant strings. Adding this attribute is essentially equivalent to
6264	providing a trivial ``+load`` method but avoids the (fairly small) load-time
6265	overheads associated with defining and calling such a method.)reST";
6266
6267	static const char AttrDoc_ObjCNonRuntimeProtocol[] = R"reST(The ``objc_non_runtime_protocol`` attribute can be used to mark that an
6268	Objective-C protocol is only used during static type-checking and doesn't need
6269	to be represented dynamically. This avoids several small code-size and run-time
6270	overheads associated with handling the protocol's metadata. A non-runtime
6271	protocol cannot be used as the operand of a ``@protocol`` expression, and
6272	dynamic attempts to find it with ``objc_getProtocol`` will fail.
6273
6274	If a non-runtime protocol inherits from any ordinary protocols, classes and
6275	derived protocols that declare conformance to the non-runtime protocol will
6276	dynamically list their conformance to those bare protocols.)reST";
6277
6278	static const char AttrDoc_ObjCOwnership[] = R"reST(No documentation.)reST";
6279
6280	static const char AttrDoc_ObjCPreciseLifetime[] = R"reST(No documentation.)reST";
6281
6282	static const char AttrDoc_ObjCRequiresPropertyDefs[] = R"reST(No documentation.)reST";
6283
6284	static const char AttrDoc_ObjCRequiresSuper[] = R"reST(Some Objective-C classes allow a subclass to override a particular method in a
6285	parent class but expect that the overriding method also calls the overridden
6286	method in the parent class. For these cases, we provide an attribute to
6287	designate that a method requires a "call to ``super``" in the overriding
6288	method in the subclass.
6289
6290	Usage: ``__attribute__((objc_requires_super))``. This attribute can only
6291	be placed at the end of a method declaration:
6292
6293	.. code-block:: objc
6294
6295	- (void)foo __attribute__((objc_requires_super));
6296
6297	This attribute can only be applied the method declarations within a class, and
6298	not a protocol. Currently this attribute does not enforce any placement of
6299	where the call occurs in the overriding method (such as in the case of
6300	``-dealloc`` where the call must appear at the end). It checks only that it
6301	exists.
6302
6303	Note that on both OS X and iOS that the Foundation framework provides a
6304	convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
6305	attribute:
6306
6307	.. code-block:: objc
6308
6309	- (void)foo NS_REQUIRES_SUPER;
6310
6311	This macro is conditionally defined depending on the compiler's support for
6312	this attribute. If the compiler does not support the attribute the macro
6313	expands to nothing.
6314
6315	Operationally, when a method has this annotation the compiler will warn if the
6316	implementation of an override in a subclass does not call super. For example:
6317
6318	.. code-block:: objc
6319
6320	warning: method possibly missing a [super AnnotMeth] call
6321	- (void) AnnotMeth{};
6322	^)reST";
6323
6324	static const char AttrDoc_ObjCReturnsInnerPointer[] = R"reST(No documentation.)reST";
6325
6326	static const char AttrDoc_ObjCRootClass[] = R"reST(No documentation.)reST";
6327
6328	static const char AttrDoc_ObjCRuntimeName[] = R"reST(By default, the Objective-C interface or protocol identifier is used
6329	in the metadata name for that object. The ``objc_runtime_name``
6330	attribute allows annotated interfaces or protocols to use the
6331	specified string argument in the object's metadata name instead of the
6332	default name.
6333
6334	Usage: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute
6335	can only be placed before an @protocol or @interface declaration:
6336
6337	.. code-block:: objc
6338
6339	__attribute__((objc_runtime_name("MyLocalName")))
6340	@interface Message
6341	@end)reST";
6342
6343	static const char AttrDoc_ObjCRuntimeVisible[] = R"reST(This attribute specifies that the Objective-C class to which it applies is
6344	visible to the Objective-C runtime but not to the linker. Classes annotated
6345	with this attribute cannot be subclassed and cannot have categories defined for
6346	them.)reST";
6347
6348	static const char AttrDoc_ObjCSubclassingRestricted[] = R"reST(This attribute can be added to an Objective-C ``@interface`` declaration to
6349	ensure that this class cannot be subclassed.)reST";
6350
6351	static const char AttrDoc_OpenACCRoutineAnnot[] = R"reST()reST";
6352
6353	static const char AttrDoc_OpenACCRoutineDecl[] = R"reST()reST";
6354
6355	static const char AttrDoc_OpenCLAccess[] = R"reST(The access qualifiers must be used with image object arguments or pipe arguments
6356	to declare if they are being read or written by a kernel or function.
6357
6358	The read_only/__read_only, write_only/__write_only and read_write/__read_write
6359	names are reserved for use as access qualifiers and shall not be used otherwise.
6360
6361	.. code-block:: c
6362
6363	kernel void
6364	foo (read_only image2d_t imageA,
6365	write_only image2d_t imageB) {
6366	...
6367	}
6368
6369	In the above example imageA is a read-only 2D image object, and imageB is a
6370	write-only 2D image object.
6371
6372	The read_write (or __read_write) qualifier can not be used with pipe.
6373
6374	More details can be found in the OpenCL C language Spec v2.0, Section 6.6.)reST";
6375
6376	static const char AttrDoc_OpenCLConstantAddressSpace[] = R"reST(The constant address space attribute signals that an object is located in
6377	a constant (non-modifiable) memory region. It is available to all work items.
6378	Any type can be annotated with the constant address space attribute. Objects
6379	with the constant address space qualifier can be declared in any scope and must
6380	have an initializer.)reST";
6381
6382	static const char AttrDoc_OpenCLGenericAddressSpace[] = R"reST(The generic address space attribute is only available with OpenCL v2.0 and later.
6383	It can be used with pointer types. Variables in global and local scope and
6384	function parameters in non-kernel functions can have the generic address space
6385	type attribute. It is intended to be a placeholder for any other address space
6386	except for '__constant' in OpenCL code which can be used with multiple address
6387	spaces.)reST";
6388
6389	static const char AttrDoc_OpenCLGlobalAddressSpace[] = R"reST(The global address space attribute specifies that an object is allocated in
6390	global memory, which is accessible by all work items. The content stored in this
6391	memory area persists between kernel executions. Pointer types to the global
6392	address space are allowed as function parameters or local variables. Starting
6393	with OpenCL v2.0, the global address space can be used with global (program
6394	scope) variables and static local variable as well.)reST";
6395
6396	static const char AttrDoc_OpenCLGlobalDeviceAddressSpace[] = R"reST(The ``global_device`` and ``global_host`` address space attributes specify that
6397	an object is allocated in global memory on the device/host. It helps to
6398	distinguish USM (Unified Shared Memory) pointers that access global device
6399	memory from those that access global host memory. These new address spaces are
6400	a subset of the ``__global/opencl_global`` address space, the full address space
6401	set model for OpenCL 2.0 with the extension looks as follows:
6402
6403	\| generic->global->host
6404	\| ->device
6405	\| ->private
6406	\| ->local
6407	\| constant
6408
6409	As ``global_device`` and ``global_host`` are a subset of
6410	``__global/opencl_global`` address spaces it is allowed to convert
6411	``global_device`` and ``global_host`` address spaces to
6412	``__global/opencl_global`` address spaces (following ISO/IEC TR 18037 5.1.3
6413	"Address space nesting and rules for pointers").)reST";
6414
6415	static const char AttrDoc_OpenCLGlobalHostAddressSpace[] = R"reST(The ``global_device`` and ``global_host`` address space attributes specify that
6416	an object is allocated in global memory on the device/host. It helps to
6417	distinguish USM (Unified Shared Memory) pointers that access global device
6418	memory from those that access global host memory. These new address spaces are
6419	a subset of the ``__global/opencl_global`` address space, the full address space
6420	set model for OpenCL 2.0 with the extension looks as follows:
6421
6422	\| generic->global->host
6423	\| ->device
6424	\| ->private
6425	\| ->local
6426	\| constant
6427
6428	As ``global_device`` and ``global_host`` are a subset of
6429	``__global/opencl_global`` address spaces it is allowed to convert
6430	``global_device`` and ``global_host`` address spaces to
6431	``__global/opencl_global`` address spaces (following ISO/IEC TR 18037 5.1.3
6432	"Address space nesting and rules for pointers").)reST";
6433
6434	static const char AttrDoc_OpenCLIntelReqdSubGroupSize[] = R"reST(The optional attribute intel_reqd_sub_group_size can be used to indicate that
6435	the kernel must be compiled and executed with the specified subgroup size. When
6436	this attribute is present, get_max_sub_group_size() is guaranteed to return the
6437	specified integer value. This is important for the correctness of many subgroup
6438	algorithms, and in some cases may be used by the compiler to generate more optimal
6439	code. See `cl_intel_required_subgroup_size
6440	<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
6441	for details.)reST";
6442
6443	static const char AttrDoc_OpenCLLocalAddressSpace[] = R"reST(The local address space specifies that an object is allocated in the local (work
6444	group) memory area, which is accessible to all work items in the same work
6445	group. The content stored in this memory region is not accessible after
6446	the kernel execution ends. In a kernel function scope, any variable can be in
6447	the local address space. In other scopes, only pointer types to the local address
6448	space are allowed. Local address space variables cannot have an initializer.)reST";
6449
6450	static const char AttrDoc_OpenCLPrivateAddressSpace[] = R"reST(The private address space specifies that an object is allocated in the private
6451	(work item) memory. Other work items cannot access the same memory area and its
6452	content is destroyed after work item execution ends. Local variables can be
6453	declared in the private address space. Function arguments are always in the
6454	private address space. Kernel function arguments of a pointer or an array type
6455	cannot point to the private address space.)reST";
6456
6457	static const char AttrDoc_OpenCLUnrollHint[] = R"reST(The opencl_unroll_hint attribute qualifier can be used to specify that a loop
6458	(for, while and do loops) can be unrolled. This attribute qualifier can be
6459	used to specify full unrolling or partial unrolling by a specified amount.
6460	This is a compiler hint and the compiler may ignore this directive. See
6461	`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
6462	s6.11.5 for details.)reST";
6463
6464	static const char AttrDoc_OptimizeNone[] = R"reST(The ``optnone`` attribute suppresses essentially all optimizations
6465	on a function or method, regardless of the optimization level applied to
6466	the compilation unit as a whole. This is particularly useful when you
6467	need to debug a particular function, but it is infeasible to build the
6468	entire application without optimization. Avoiding optimization on the
6469	specified function can improve the quality of the debugging information
6470	for that function.
6471
6472	This attribute is incompatible with the ``always_inline`` and ``minsize``
6473	attributes.
6474
6475	Note that this attribute does not apply recursively to nested functions such as
6476	lambdas or blocks when using declaration-specific attribute syntaxes such as double
6477	square brackets (``[[]]``) or ``__attribute__``. The ``#pragma`` syntax can be
6478	used to apply the attribute to all functions, including nested functions, in a
6479	range of source code.)reST";
6480
6481	static const char AttrDoc_OverflowBehavior[] = R"reST(No documentation.)reST";
6482
6483	static const char AttrDoc_Overloadable[] = R"reST(Clang provides support for C++ function overloading in C. Function overloading
6484	in C is introduced using the ``overloadable`` attribute. For example, one
6485	might provide several overloaded versions of a ``tgsin`` function that invokes
6486	the appropriate standard function computing the sine of a value with ``float``,
6487	``double``, or ``long double`` precision:
6488
6489	.. code-block:: c
6490
6491	#include <math.h>
6492	float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
6493	double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
6494	long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
6495
6496	Given these declarations, one can call ``tgsin`` with a ``float`` value to
6497	receive a ``float`` result, with a ``double`` to receive a ``double`` result,
6498	etc. Function overloading in C follows the rules of C++ function overloading
6499	to pick the best overload given the call arguments, with a few C-specific
6500	semantics:
6501
6502	* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
6503	floating-point promotion (per C99) rather than as a floating-point conversion
6504	(as in C++).
6505
6506	* A conversion from a pointer of type ``T`` to a pointer of type ``U`` is
6507	considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
6508	compatible types.
6509
6510	* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
6511	and ``U`` are compatible types. This conversion is given "conversion" rank.
6512
6513	* If no viable candidates are otherwise available, we allow a conversion from a
6514	pointer of type ``T`` to a pointer of type ``U``, where ``T`` and ``U`` are
6515	incompatible. This conversion is ranked below all other types of conversions.
6516	Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
6517	for ``T`` and ``U`` to be incompatible.
6518
6519	The declaration of ``overloadable`` functions is restricted to function
6520	declarations and definitions. If a function is marked with the ``overloadable``
6521	attribute, then all declarations and definitions of functions with that name,
6522	except for at most one (see the note below about unmarked overloads), must have
6523	the ``overloadable`` attribute. In addition, redeclarations of a function with
6524	the ``overloadable`` attribute must have the ``overloadable`` attribute, and
6525	redeclarations of a function without the ``overloadable`` attribute must not
6526	have the ``overloadable`` attribute. e.g.,
6527
6528	.. code-block:: c
6529
6530	int f(int) __attribute__((overloadable));
6531	float f(float); // error: declaration of "f" must have the "overloadable" attribute
6532	int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
6533
6534	int g(int) __attribute__((overloadable));
6535	int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
6536
6537	int h(int);
6538	int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
6539	// have the "overloadable" attribute
6540
6541	Functions marked ``overloadable`` must have prototypes. Therefore, the
6542	following code is ill-formed:
6543
6544	.. code-block:: c
6545
6546	int h() __attribute__((overloadable)); // error: h does not have a prototype
6547
6548	However, ``overloadable`` functions are allowed to use a ellipsis even if there
6549	are no named parameters (as is permitted in C++). This feature is particularly
6550	useful when combined with the ``unavailable`` attribute:
6551
6552	.. code-block:: c++
6553
6554	void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
6555
6556	Functions declared with the ``overloadable`` attribute have their names mangled
6557	according to the same rules as C++ function names. For example, the three
6558	``tgsin`` functions in our motivating example get the mangled names
6559	``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
6560	caveats to this use of name mangling:
6561
6562	* Future versions of Clang may change the name mangling of functions overloaded
6563	in C, so you should not depend on an specific mangling. To be completely
6564	safe, we strongly urge the use of ``static inline`` with ``overloadable``
6565	functions.
6566
6567	* The ``overloadable`` attribute has almost no meaning when used in C++,
6568	because names will already be mangled and functions are already overloadable.
6569	However, when an ``overloadable`` function occurs within an ``extern "C"``
6570	linkage specification, its name will be mangled in the same way as it
6571	would in C.
6572
6573	For the purpose of backwards compatibility, at most one function with the same
6574	name as other ``overloadable`` functions may omit the ``overloadable``
6575	attribute. In this case, the function without the ``overloadable`` attribute
6576	will not have its name mangled.
6577
6578	For example:
6579
6580	.. code-block:: c
6581
6582	// Notes with mangled names assume Itanium mangling.
6583	int f(int);
6584	int f(double) __attribute__((overloadable));
6585	void foo() {
6586	f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
6587	// was marked with overloadable).
6588	f(1.0); // Emits a call to _Z1fd.
6589	}
6590
6591	Support for unmarked overloads is not present in some versions of clang. You may
6592	query for it using ``__has_extension(overloadable_unmarked)``.
6593
6594	Query for this attribute with ``__has_attribute(overloadable)``.)reST";
6595
6596	static const char AttrDoc_Override[] = R"reST()reST";
6597
6598	static const char AttrDoc_Owner[] = R"reST(.. Note:: This attribute is experimental and its effect on analysis is subject to change in
6599	a future version of clang.
6600
6601	The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an
6602	object of type ``T``:
6603
6604	.. code::
6605
6606	class [[gsl::Owner(int)]] IntOwner {
6607	private:
6608	int value;
6609	public:
6610	int *getInt() { return &value; }
6611	};
6612
6613	The argument ``T`` is optional and is ignored.
6614	This attribute may be used by analysis tools and has no effect on code
6615	generation. A ``void`` argument means that the class can own any type.
6616
6617	See Pointer_ for an example.)reST";
6618
6619	static const char AttrDoc_Ownership[] = R"reST(.. note::
6620
6621	In order for the Clang Static Analyzer to acknowledge these attributes, the
6622	``Optimistic`` config needs to be set to true for the checker
6623	``unix.DynamicMemoryModeling``:
6624
6625	``-Xclang -analyzer-config -Xclang unix.DynamicMemoryModeling:Optimistic=true``
6626
6627	These attributes are used by the Clang Static Analyzer's dynamic memory modeling
6628	facilities to mark custom allocating/deallocating functions.
6629
6630	All 3 attributes' first parameter of type string is the type of the allocation:
6631	``malloc``, ``new``, etc. to allow for catching :ref:`mismatched deallocation
6632	<unix-MismatchedDeallocator>` bugs. The allocation type can be any string, e.g.
6633	a function annotated with
6634	returning a piece of memory of type ``lasagna`` but freed with a function
6635	annotated to release ``cheese`` typed memory will result in mismatched
6636	deallocation warning.
6637
6638	The (currently) only allocation type having special meaning is ``malloc`` --
6639	the Clang Static Analyzer makes sure that allocating functions annotated with
6640	``malloc`` are treated like they used the standard ``malloc()``, and can be
6641	safely deallocated with the standard ``free()``.
6642
6643	* Use ``ownership_returns`` to mark a function as an allocating function. Takes
6644	1 parameter to denote the allocation type.
6645	* Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2
6646	parameters: the allocation type, and the index of the parameter that is being
6647	deallocated (counting from 1).
6648	* Use ``ownership_holds`` to mark that a function takes over the ownership of a
6649	piece of memory and will free it at some unspecified point in the future. Like
6650	``ownership_takes``, this takes 2 parameters: the allocation type, and the
6651	index of the parameter whose ownership will be taken over (counting from 1).
6652
6653	The annotations ``ownership_takes`` and ``ownership_holds`` both prevent memory
6654	leak reports (concerning the specified argument); the difference between them
6655	is that using taken memory is a use-after-free error, while using held memory
6656	is assumed to be legitimate.
6657
6658	Example:
6659
6660	.. code-block:: c
6661
6662	// Denotes that my_malloc will return with a dynamically allocated piece of
6663	// memory using malloc().
6664	void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
6665
6666	// Denotes that my_free will deallocate its parameter using free().
6667	void __attribute((ownership_takes(malloc, 1))) my_free(void *);
6668
6669	// Denotes that my_hold will take over the ownership of its parameter that was
6670	// allocated via malloc().
6671	void __attribute((ownership_holds(malloc, 1))) my_hold(void *);
6672
6673	Further reading about dynamic memory modeling in the Clang Static Analyzer is
6674	found in these checker docs:
6675	:ref:`unix.Malloc <unix-Malloc>`, :ref:`unix.MallocSizeof <unix-MallocSizeof>`,
6676	:ref:`unix.MismatchedDeallocator <unix-MismatchedDeallocator>`,
6677	:ref:`cplusplus.NewDelete <cplusplus-NewDelete>`,
6678	:ref:`cplusplus.NewDeleteLeaks <cplusplus-NewDeleteLeaks>`,
6679	:ref:`optin.taint.TaintedAlloc <optin-taint-TaintedAlloc>`.
6680	Mind that many more checkers are affected by dynamic memory modeling changes to
6681	some extent.
6682
6683	Further reading for other annotations:
6684	`Source Annotations in the Clang Static Analyzer <https://clang.llvm.org/docs/analyzer/user-docs/Annotations.html>`_.)reST";
6685
6686	static const char AttrDoc_Packed[] = R"reST(No documentation.)reST";
6687
6688	static const char AttrDoc_ParamTypestate[] = R"reST(This attribute specifies expectations about function parameters. Calls to an
6689	function with annotated parameters will issue a warning if the corresponding
6690	argument isn't in the expected state. The attribute is also used to set the
6691	initial state of the parameter when analyzing the function's body.)reST";
6692
6693	static const char AttrDoc_Pascal[] = R"reST(No documentation.)reST";
6694
6695	static const char AttrDoc_PassObjectSize[] = R"reST(.. Note:: The mangling of functions with parameters that are annotated with
6696	``pass_object_size`` is subject to change. You can get around this by
6697	using ``__asm__("foo")`` to explicitly name your functions, thus preserving
6698	your ABI; also, non-overloadable C functions with ``pass_object_size`` are
6699	not mangled.
6700
6701	The ``pass_object_size(Type)`` attribute can be placed on function parameters to
6702	instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
6703	of said function, and implicitly pass the result of this call in as an invisible
6704	argument of type ``size_t`` directly after the parameter annotated with
6705	``pass_object_size``. Clang will also replace any calls to
6706	``__builtin_object_size(param, Type)`` in the function by said implicit
6707	parameter.
6708
6709	Example usage:
6710
6711	.. code-block:: c
6712
6713	int bzero1(char *const p __attribute__((pass_object_size(0))))
6714	__attribute__((noinline)) {
6715	int i = 0;
6716	for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
6717	p[i] = 0;
6718	}
6719	return i;
6720	}
6721
6722	int main() {
6723	char chars[100];
6724	int n = bzero1(&chars[0]);
6725	assert(n == sizeof(chars));
6726	return 0;
6727	}
6728
6729	If successfully evaluating ``__builtin_object_size(param, Type)`` at the
6730	callsite is not possible, then the "failed" value is passed in. So, using the
6731	definition of ``bzero1`` from above, the following code would exit cleanly:
6732
6733	.. code-block:: c
6734
6735	int main2(int argc, char *argv[]) {
6736	int n = bzero1(argv);
6737	assert(n == -1);
6738	return 0;
6739	}
6740
6741	``pass_object_size`` plays a part in overload resolution. If two overload
6742	candidates are otherwise equally good, then the overload with one or more
6743	parameters with ``pass_object_size`` is preferred. This implies that the choice
6744	between two identical overloads both with ``pass_object_size`` on one or more
6745	parameters will always be ambiguous; for this reason, having two such overloads
6746	is illegal. For example:
6747
6748	.. code-block:: c++
6749
6750	#define PS(N) __attribute__((pass_object_size(N)))
6751	// OK
6752	void Foo(char a, char b); // Overload A
6753	// OK -- overload A has no parameters with pass_object_size.
6754	void Foo(char a PS(0), char b PS(0)); // Overload B
6755	// Error -- Same signature (sans pass_object_size) as overload B, and both
6756	// overloads have one or more parameters with the pass_object_size attribute.
6757	void Foo(void a PS(0), void b);
6758
6759	// OK
6760	void Bar(void *a PS(0)); // Overload C
6761	// OK
6762	void Bar(char *c PS(1)); // Overload D
6763
6764	void main() {
6765	char known[10], *unknown;
6766	Foo(unknown, unknown); // Calls overload B
6767	Foo(known, unknown); // Calls overload B
6768	Foo(unknown, known); // Calls overload B
6769	Foo(known, known); // Calls overload B
6770
6771	Bar(known); // Calls overload D
6772	Bar(unknown); // Calls overload D
6773	}
6774
6775	Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
6776
6777	* Only one use of ``pass_object_size`` is allowed per parameter.
6778
6779	* It is an error to take the address of a function with ``pass_object_size`` on
6780	any of its parameters. If you wish to do this, you can create an overload
6781	without ``pass_object_size`` on any parameters.
6782
6783	* It is an error to apply the ``pass_object_size`` attribute to parameters that
6784	are not pointers. Additionally, any parameter that ``pass_object_size`` is
6785	applied to must be marked ``const`` at its function's definition.
6786
6787	Clang also supports the ``pass_dynamic_object_size`` attribute, which behaves
6788	identically to ``pass_object_size``, but evaluates a call to
6789	``__builtin_dynamic_object_size`` at the callee instead of
6790	``__builtin_object_size``. ``__builtin_dynamic_object_size`` provides some extra
6791	runtime checks when the object size can't be determined at compile-time. You can
6792	read more about ``__builtin_dynamic_object_size`` `here
6793	<https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically>`_.)reST";
6794
6795	static const char AttrDoc_PatchableFunctionEntry[] = R"reST(``__attribute__((patchable_function_entry(N,M,Section)))`` is used to generate M
6796	NOPs before the function entry and N-M NOPs after the function entry, with a record of
6797	the entry stored in section ``Section``. This attribute takes precedence over the
6798	command line option ``-fpatchable-function-entry=N,M,Section``. ``M`` defaults to 0
6799	if omitted.``Section`` defaults to the ``-fpatchable-function-entry`` section name if
6800	set, or to ``__patchable_function_entries`` otherwise.
6801
6802	This attribute is only supported on
6803	aarch64/aarch64-be/loongarch32/loongarch64/riscv32/riscv64/i386/x86-64/ppc/ppc64/ppc64le/s390x targets.
6804	For ppc/ppc64 targets, AIX is still not supported.)reST";
6805
6806	static const char AttrDoc_Pcs[] = R"reST(On ARM targets, this attribute can be used to select calling conventions
6807	similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
6808	"aapcs-vfp".)reST";
6809
6810	static const char AttrDoc_Personality[] = R"reST(``__attribute__((personality(<routine>)))`` is used to specify a personality
6811	routine that is different from the language that is being used to implement the
6812	function. This is a targeted, low-level feature aimed at language runtime
6813	implementors who write runtime support code in C/C++ but need that code to
6814	participate in a foreign language's exception-handling or unwinding model.
6815
6816	A personality routine is a language-specific callback attached to each stack
6817	frame that the unwinder invokes to determine whether that frame handles a given
6818	exception and what cleanup actions to perform. It effectively colors the
6819	language-agnostic unwinding mechanism with language-specific semantics, enabling
6820	different languages to coexist on the same call stack while each interpreting
6821	exceptions according to their own rules.)reST";
6822
6823	static const char AttrDoc_Pointer[] = R"reST(.. Note:: This attribute is experimental and its effect on analysis is subject to change in
6824	a future version of clang.
6825
6826	The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave
6827	like pointers to an object of type ``T``:
6828
6829	.. code::
6830
6831	class [[gsl::Pointer(int)]] IntPointer {
6832	private:
6833	int *valuePointer;
6834	public:
6835	IntPointer(const IntOwner&);
6836	int *getInt() { return valuePointer; }
6837	};
6838
6839	The argument ``T`` is optional and is ignored.
6840	This attribute may be used by analysis tools and has no effect on code
6841	generation. A ``void`` argument means that the pointer can point to any type.
6842
6843	Example:
6844	When constructing an instance of a class annotated like this (a Pointer) from
6845	an instance of a class annotated with ``[[gsl::Owner]]`` (an Owner),
6846	then the analysis will consider the Pointer to point inside the Owner.
6847	When the Owner's lifetime ends, it will consider the Pointer to be dangling.
6848
6849	.. code-block:: c++
6850
6851	int f() {
6852	IntPointer P(IntOwner{}); // P "points into" a temporary IntOwner object
6853	P.getInt(); // P is dangling
6854	}
6855
6856	Transparent Member Functions
6857
6858	The analysis automatically tracks certain member functions of ``[[gsl::Pointer]]`` types
6859	that provide transparent access to the pointed-to object. These include:
6860
6861	* Dereference operators: ``operator*``, ``operator->``
6862	* Data access methods: ``data()``, ``c_str()``, ``get()``
6863	* Iterator methods: ``begin()``, ``end()``, ``rbegin()``, ``rend()``, ``cbegin()``, ``cend()``, ``crbegin()``, ``crend()``
6864
6865	When these methods return pointers, view types, or references, the analysis treats them as
6866	transparently borrowing from the same object that the pointer itself borrows from,
6867	enabling detection of use-after-free through these access patterns:
6868
6869	.. code-block:: c++
6870
6871	// For example, .data() here returns a borrow to 's' instead of 'v'.
6872	const char* f() {
6873	std::string s = "hello";
6874	std::string_view v = s; // warning: address of stack memory returned
6875	return v.data(); // note: returned here
6876	}
6877
6878	const MyObj& g(MyObj obj) {
6879	View v = obj; // warning: address of stack memory returned
6880	return *v; // note: returned here
6881	}
6882
6883	This tracking also applies to range-based for loops, where the ``begin()`` and ``end()``
6884	iterators are used to access elements:
6885
6886	.. code-block:: c++
6887
6888	std::string_view f(std::vector<std::string> vec) {
6889	for (const std::string& s : vec) { // warning: address of stack memory returned
6890	return s; // note: returned here
6891	}
6892	}
6893
6894	Container Template Specialization
6895
6896	If a template class is annotated with ``[[gsl::Owner]]``, and the first
6897	instantiated template argument is a pointer type (raw pointer, or ``[[gsl::Pointer]]``),
6898	the analysis will consider the instantiated class as a container of the pointer.
6899	When constructing such an object from a GSL owner object, the analysis will
6900	assume that the container holds a pointer to the owner object. Consequently,
6901	when the owner object is destroyed, the pointer will be considered dangling.
6902
6903	.. code-block:: c++
6904
6905	int f() {
6906	std::vector<std::string_view> v = {std::string()}; // v holds a dangling pointer.
6907	std::optional<std::string_view> o = std::string(); // o holds a dangling pointer.
6908	})reST";
6909
6910	static const char AttrDoc_PointerAuth[] = R"reST(The ``__ptrauth`` qualifier allows the programmer to directly control
6911	how pointers are signed when they are stored in a particular variable.
6912	This can be used to strengthen the default protections of pointer
6913	authentication and make it more difficult for an attacker to escalate
6914	an ability to alter memory into full control of a process.
6915
6916	.. code-block:: c
6917
6918	#include <ptrauth.h>
6919
6920	typedef void (my_callback)(const void);
6921	my_callback __ptrauth(ptrauth_key_process_dependent_code, 1, 0xe27a) callback;
6922
6923	The first argument to ``__ptrauth`` is the name of the signing key.
6924	Valid key names for the target are defined in ``<ptrauth.h>``.
6925
6926	The second argument to ``__ptrauth`` is a flag (0 or 1) specifying whether
6927	the object should use address discrimination.
6928
6929	The third argument to ``__ptrauth`` is a 16-bit non-negative integer which
6930	allows additional discrimination between objects.)reST";
6931
6932	static const char AttrDoc_PointerFieldProtection[] = R"reST(No documentation.)reST";
6933
6934	static const char AttrDoc_PragmaClangBSSSection[] = R"reST()reST";
6935
6936	static const char AttrDoc_PragmaClangDataSection[] = R"reST()reST";
6937
6938	static const char AttrDoc_PragmaClangRelroSection[] = R"reST()reST";
6939
6940	static const char AttrDoc_PragmaClangRodataSection[] = R"reST()reST";
6941
6942	static const char AttrDoc_PragmaClangTextSection[] = R"reST()reST";
6943
6944	static const char AttrDoc_PreferredName[] = R"reST(The ``preferred_name`` attribute can be applied to a class template, and
6945	specifies a preferred way of naming a specialization of the template. The
6946	preferred name will be used whenever the corresponding template specialization
6947	would otherwise be printed in a diagnostic or similar context.
6948
6949	The preferred name must be a typedef or type alias declaration that refers to a
6950	specialization of the class template (not including any type qualifiers). In
6951	general this requires the template to be declared at least twice. For example:
6952
6953	.. code-block:: c++
6954
6955	template<typename T> struct basic_string;
6956	using string = basic_string<char>;
6957	using wstring = basic_string<wchar_t>;
6958	template<typename T> struct [[clang::preferred_name(string),
6959	clang::preferred_name(wstring)]] basic_string {
6960	// ...
6961	};
6962
6963
6964	Note that the ``preferred_name`` attribute will be ignored when the compiler
6965	writes a C++20 Module interface now. This is due to a compiler issue
6966	(https://github.com/llvm/llvm-project/issues/56490) that blocks users to modularize
6967	declarations with `preferred_name`. This is intended to be fixed in the future.)reST";
6968
6969	static const char AttrDoc_PreferredType[] = R"reST(This attribute allows adjusting the type of a bit-field in debug information.
6970	This can be helpful when a bit-field is intended to store an enumeration value,
6971	but has to be specified as having the enumeration's underlying type in order to
6972	facilitate compiler optimizations or bit-field packing behavior. Normally, the
6973	underlying type is what is emitted in debug information, which can make it hard
6974	for debuggers to know to map a bit-field's value back to a particular enumeration.
6975
6976	.. code-block:: c++
6977
6978	enum Colors { Red, Green, Blue };
6979
6980	struct S {
6981	[[clang::preferred_type(Colors)]] unsigned ColorVal : 2;
6982	[[clang::preferred_type(bool)]] unsigned UseAlternateColorSpace : 1;
6983	} s = { Green, false };
6984
6985	Without the attribute, a debugger is likely to display the value ``1`` for ``ColorVal``
6986	and ``0`` for ``UseAlternateColorSpace``. With the attribute, the debugger may now
6987	display ``Green`` and ``false`` instead.
6988
6989	This can be used to map a bit-field to an arbitrary type that isn't integral
6990	or an enumeration type. For example:
6991
6992	.. code-block:: c++
6993
6994	struct A {
6995	short a1;
6996	short a2;
6997	};
6998
6999	struct B {
7000	[[clang::preferred_type(A)]] unsigned b1 : 32 = 0x000F'000C;
7001	};
7002
7003	will associate the type ``A`` with the ``b1`` bit-field and is intended to display
7004	something like this in the debugger:
7005
7006	.. code-block:: text
7007
7008	Process 2755547 stopped
7009	* thread #1, name = 'test-preferred-', stop reason = step in
7010	frame #0: 0x0000555555555148 test-preferred-type`main at test.cxx:13:14
7011	10 int main()
7012	11 {
7013	12 B b;
7014	-> 13 return b.b1;
7015	14 }
7016	(lldb) v -T
7017	(B) b = {
7018	(A:32) b1 = {
7019	(short) a1 = 12
7020	(short) a2 = 15
7021	}
7022	}
7023
7024	Note that debuggers may not be able to handle more complex mappings, and so
7025	this usage is debugger-dependent.)reST";
7026
7027	static const char AttrDoc_PreserveAll[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of
7028	a function. The ``preserve_all`` calling convention attempts to make the code
7029	in the caller even less intrusive than the ``preserve_most`` calling convention.
7030	This calling convention also behaves identical to the ``C`` calling convention
7031	on how arguments and return values are passed, but it uses a different set of
7032	caller/callee-saved registers. This removes the burden of saving and
7033	recovering a large register set before and after the call in the caller. If
7034	the arguments are passed in callee-saved registers, then they will be
7035	preserved by the callee across the call. This doesn't apply for values
7036	returned in callee-saved registers.
7037
7038	- On X86-64 the callee preserves all general purpose registers, except for
7039	R11. R11 can be used as a scratch register. Furthermore it also preserves
7040	all floating-point registers (XMMs/YMMs).
7041
7042	- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
7043	X16-X18. Furthermore it also preserves lower 128 bits of V8-V31 SIMD - floating
7044	point registers.
7045
7046	The idea behind this convention is to support calls to runtime functions
7047	that don't need to call out to any other functions.
7048
7049	This calling convention, like the ``preserve_most`` calling convention, will be
7050	used by a future version of the Objective-C runtime and should be considered
7051	experimental at this time.)reST";
7052
7053	static const char AttrDoc_PreserveMost[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of
7054	a function. The ``preserve_most`` calling convention attempts to make the code
7055	in the caller as unintrusive as possible. This convention behaves identically
7056	to the ``C`` calling convention on how arguments and return values are passed,
7057	but it uses a different set of caller/callee-saved registers. This alleviates
7058	the burden of saving and recovering a large register set before and after the
7059	call in the caller. If the arguments are passed in callee-saved registers,
7060	then they will be preserved by the callee across the call. This doesn't
7061	apply for values returned in callee-saved registers.
7062
7063	- On X86-64 the callee preserves all general purpose registers, except for
7064	R11. R11 can be used as a scratch register. Floating-point registers
7065	(XMMs/YMMs) are not preserved and need to be saved by the caller.
7066
7067	- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
7068	X16-X18.
7069
7070	The idea behind this convention is to support calls to runtime functions
7071	that have a hot path and a cold path. The hot path is usually a small piece
7072	of code that doesn't use many registers. The cold path might need to call out to
7073	another function and therefore only needs to preserve the caller-saved
7074	registers, which haven't already been saved by the caller. The
7075	``preserve_most`` calling convention is very similar to the ``cold`` calling
7076	convention in terms of caller/callee-saved registers, but they are used for
7077	different types of function calls. ``coldcc`` is for function calls that are
7078	rarely executed, whereas ``preserve_most`` function calls are intended to be
7079	on the hot path and definitely executed a lot. Furthermore ``preserve_most``
7080	doesn't prevent the inliner from inlining the function call.
7081
7082	This calling convention will be used by a future version of the Objective-C
7083	runtime and should therefore still be considered experimental at this time.
7084	Although this convention was created to optimize certain runtime calls to
7085	the Objective-C runtime, it is not limited to this runtime and might be used
7086	by other runtimes in the future too. The current implementation only
7087	supports X86-64 and AArch64, but the intention is to support more architectures
7088	in the future.)reST";
7089
7090	static const char AttrDoc_PreserveNone[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of a function.
7091	The ``preserve_none`` calling convention tries to preserve as few general
7092	registers as possible. So all general registers are caller saved registers. It
7093	also uses more general registers to pass arguments. This attribute doesn't
7094	impact floating-point registers. ``preserve_none``'s ABI is still unstable, and
7095	may be changed in the future.
7096
7097	- On X86-64, only RSP and RBP are preserved by the callee.
7098	Registers R12, R13, R14, R15, RDI, RSI, RDX, RCX, R8, R9, R11, and RAX now can
7099	be used to pass function arguments. Floating-point registers (XMMs/YMMs) still
7100	follow the C calling convention.
7101	- On AArch64, only LR and FP are preserved by the callee.
7102	Registers X20-X28, X0-X7, and X9-X14 are used to pass function arguments.
7103	X8, X16-X19, SIMD and floating-point registers follow the AAPCS calling
7104	convention. X15 is not available for argument passing on Windows, but is
7105	used to pass arguments on other platforms.)reST";
7106
7107	static const char AttrDoc_PtGuardedBy[] = R"reST(No documentation.)reST";
7108
7109	static const char AttrDoc_PtGuardedVar[] = R"reST(No documentation.)reST";
7110
7111	static const char AttrDoc_Ptr32[] = R"reST(The ``__ptr32`` qualifier represents a native pointer on a 32-bit system. On a
7112	64-bit system, a pointer with ``__ptr32`` is extended to a 64-bit pointer. The
7113	``__sptr`` and ``__uptr`` qualifiers can be used to specify whether the pointer
7114	is sign extended or zero extended. This qualifier is enabled under
7115	``-fms-extensions``.)reST";
7116
7117	static const char AttrDoc_Ptr64[] = R"reST(The ``__ptr64`` qualifier represents a native pointer on a 64-bit system. On a
7118	32-bit system, a ``__ptr64`` pointer is truncated to a 32-bit pointer. This
7119	qualifier is enabled under ``-fms-extensions``.)reST";
7120
7121	static const char AttrDoc_Pure[] = R"reST(No documentation.)reST";
7122
7123	static const char AttrDoc_RISCVInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV
7124	targets. This attribute may be attached to a function definition and instructs
7125	the backend to generate appropriate function entry/exit code so that it can be
7126	used directly as an interrupt service routine.
7127
7128	Permissible values for this parameter are ``machine``, ``supervisor``,
7129	``rnmi``, ``qci-nest``, ``qci-nonest``, ``SiFive-CLIC-preemptible``, and
7130	``SiFive-CLIC-stack-swap``. If there is no parameter, then it defaults to
7131	``machine``.
7132
7133	The ``rnmi`` value is used for resumable non-maskable interrupts. It requires the
7134	standard Smrnmi extension.
7135
7136	The ``qci-nest`` and ``qci-nonest`` values require Qualcomm's Xqciint extension
7137	and are used for Machine-mode Interrupts and Machine-mode Non-maskable
7138	interrupts. These use the following instructions from Xqciint to save and
7139	restore interrupt state to the stack -- the ``qci-nest`` value will use
7140	``qc.c.mienter.nest`` and the ``qci-nonest`` value will use ``qc.c.mienter`` to
7141	begin the interrupt handler. Both of these will use ``qc.c.mileaveret`` to
7142	restore the state and return to the previous context.
7143
7144	The ``SiFive-CLIC-preemptible`` and ``SiFive-CLIC-stack-swap`` values are used
7145	for machine-mode interrupts. For ``SiFive-CLIC-preemptible`` interrupts, the
7146	values of ``mcause`` and ``mepc`` are saved onto the stack, and interrupts are
7147	re-enabled. For ``SiFive-CLIC-stack-swap`` interrupts, the stack pointer is
7148	swapped with ``mscratch`` before its first use and after its last use.
7149
7150	The SiFive CLIC values may be combined with each other and with the ``machine``
7151	attribute value. Any other combination of different values is not allowed.
7152
7153	Repeated interrupt attribute on the same declaration will cause a warning
7154	to be emitted. In case of repeated declarations, the last one prevails.
7155
7156	Refer to:
7157	https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
7158	https://riscv.org/specifications/privileged-isa/
7159	The RISC-V Instruction Set Manual Volume II: Privileged Architecture
7160	Version 1.10.
7161	https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0
7162	https://sifive.cdn.prismic.io/sifive/d1984d2b-c9b9-4c91-8de0-d68a5e64fa0f_sifive-interrupt-cookbook-v1p2.pdf)reST";
7163
7164	static const char AttrDoc_RISCVVLSCC[] = R"reST(The ``riscv_vls_cc`` attribute can be applied to a function. Functions
7165	declared with this attribute will utilize the standard fixed-length vector
7166	calling convention variant instead of the default calling convention defined by
7167	the ABI. This variant aims to pass fixed-length vectors via vector registers,
7168	if possible, rather than through general-purpose registers.)reST";
7169
7170	static const char AttrDoc_RISCVVectorCC[] = R"reST(The ``riscv_vector_cc`` attribute can be applied to a function. It preserves 15
7171	registers namely, v1-v7 and v24-v31 as callee-saved. Callers thus don't need
7172	to save these registers before function calls, and callees only need to save
7173	them if they use them.)reST";
7174
7175	static const char AttrDoc_RandomizeLayout[] = R"reST(The attribute ``randomize_layout``, when attached to a C structure, selects it
7176	for structure layout field randomization; a compile-time hardening technique. A
7177	"seed" value, is specified via the ``-frandomize-layout-seed=`` command line flag.
7178	For example:
7179
7180	.. code-block:: bash
7181
7182	SEED=`od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n'`
7183	make ... CFLAGS="-frandomize-layout-seed=$SEED" ...
7184
7185	You can also supply the seed in a file with ``-frandomize-layout-seed-file=``.
7186	For example:
7187
7188	.. code-block:: bash
7189
7190	od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n' > /tmp/seed_file.txt
7191	make ... CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt" ...
7192
7193	The randomization is deterministic based for a given seed, so the entire
7194	program should be compiled with the same seed, but keep the seed safe
7195	otherwise.
7196
7197	The attribute ``no_randomize_layout``, when attached to a C structure,
7198	instructs the compiler that this structure should not have its field layout
7199	randomized.)reST";
7200
7201	static const char AttrDoc_ReadOnlyPlacement[] = R"reST(This attribute is attached to a structure, class or union declaration.
7202	When attached to a record declaration/definition, it checks if all instances
7203	of this type can be placed in the read-only data segment of the program. If it
7204	finds an instance that can not be placed in a read-only segment, the compiler
7205	emits a warning at the source location where the type was used.
7206
7207	Examples:
7208	* ``struct __attribute__((enforce_read_only_placement)) Foo;``
7209	* ``struct __attribute__((enforce_read_only_placement)) Bar { ... };``
7210
7211	Both ``Foo`` and ``Bar`` types have the ``enforce_read_only_placement`` attribute.
7212
7213	The goal of introducing this attribute is to assist developers with writing secure
7214	code. A ``const``-qualified global is generally placed in the read-only section
7215	of the memory that has additional run time protection from malicious writes. By
7216	attaching this attribute to a declaration, the developer can express the intent
7217	to place all instances of the annotated type in the read-only program memory.
7218
7219	Note 1: The attribute doesn't guarantee that the object will be placed in the
7220	read-only data segment as it does not instruct the compiler to ensure such
7221	a placement. It emits a warning if something in the code can be proven to prevent
7222	an instance from being placed in the read-only data segment.
7223
7224	Note 2: Currently, clang only checks if all global declarations of a given type 'T'
7225	are ``const``-qualified. The following conditions would also prevent the data to be
7226	put into read only segment, but the corresponding warnings are not yet implemented.
7227
7228	1. An instance of type ``T`` is allocated on the heap/stack.
7229	2. Type ``T`` defines/inherits a mutable field.
7230	3. Type ``T`` defines/inherits non-constexpr constructor(s) for initialization.
7231	4. A field of type ``T`` is defined by type ``Q``, which does not bear the
7232	``enforce_read_only_placement`` attribute.
7233	5. A type ``Q`` inherits from type ``T`` and it does not have the
7234	``enforce_read_only_placement`` attribute.)reST";
7235
7236	static const char AttrDoc_ReentrantCapability[] = R"reST(No documentation.)reST";
7237
7238	static const char AttrDoc_RegCall[] = R"reST(On x86 targets, this attribute changes the calling convention to
7239	`__regcall`_ convention. This convention aims to pass as many arguments
7240	as possible in registers. It also tries to utilize registers for the
7241	return value whenever it is possible.
7242
7243	.. _`__regcall`: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2023-2/c-c-sycl-calling-conventions.html)reST";
7244
7245	static const char AttrDoc_Reinitializes[] = R"reST(The ``reinitializes`` attribute can be applied to a non-static, non-const C++
7246	member function to indicate that this member function reinitializes the entire
7247	object to a known state, independent of the previous state of the object.
7248
7249	This attribute can be interpreted by static analyzers that warn about uses of an
7250	object that has been left in an indeterminate state by a move operation. If a
7251	member function marked with the ``reinitializes`` attribute is called on a
7252	moved-from object, the analyzer can conclude that the object is no longer in an
7253	indeterminate state.
7254
7255	A typical example where this attribute would be used is on functions that clear
7256	a container class:
7257
7258	.. code-block:: c++
7259
7260	template <class T>
7261	class Container {
7262	public:
7263	...
7264	[[clang::reinitializes]] void Clear();
7265	...
7266	};)reST";
7267
7268	static const char AttrDoc_ReleaseCapability[] = R"reST(Marks a function as releasing a capability.)reST";
7269
7270	static const char AttrDoc_ReleaseHandle[] = R"reST(If a function parameter is annotated with ``release_handle(tag)`` it is assumed to
7271	close the handle. It is also assumed to require an open handle to work with. The
7272	attribute requires a string literal argument to identify the handle being released.
7273
7274	.. code-block:: c++
7275
7276	zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle("tag")]]);)reST";
7277
7278	static const char AttrDoc_ReqdWorkGroupSize[] = R"reST(No documentation.)reST";
7279
7280	static const char AttrDoc_RequiresCapability[] = R"reST(No documentation.)reST";
7281
7282	static const char AttrDoc_Restrict[] = R"reST(The ``malloc`` attribute has two forms with different functionality. The first
7283	is when it is used without arguments, where it marks that a function acts like
7284	a system memory allocation function, returning a pointer to allocated storage
7285	that does not alias storage from any other object accessible to the caller.
7286
7287	The second form is when ``malloc`` takes one or two arguments. The first
7288	argument names a function that should be associated with this function as its
7289	deallocation function. When this form is used, it enables the compiler to
7290	diagnose when the incorrect deallocation function is used with this variable.
7291	However the associated warning, spelled `-Wmismatched-dealloc` in GCC, is not
7292	yet implemented in clang.)reST";
7293
7294	static const char AttrDoc_Retain[] = R"reST(This attribute, when attached to a function or variable definition, prevents
7295	section garbage collection in the linker. It does not prevent other discard
7296	mechanisms, such as archive member selection, and COMDAT group resolution.
7297
7298	If the compiler does not emit the definition, e.g. because it was not used in
7299	the translation unit or the compiler was able to eliminate all of the uses,
7300	this attribute has no effect. This attribute is typically combined with the
7301	``used`` attribute to force the definition to be emitted and preserved into the
7302	final linked image.
7303
7304	This attribute is only necessary on ELF targets; other targets prevent section
7305	garbage collection by the linker when using the ``used`` attribute alone.
7306	Using the attributes together should result in consistent behavior across
7307	targets.
7308
7309	This attribute requires the linker to support the ``SHF_GNU_RETAIN`` extension.
7310	This support is available in GNU ``ld`` and ``gold`` as of binutils 2.36, as
7311	well as in ``ld.lld`` 13.)reST";
7312
7313	static const char AttrDoc_ReturnTypestate[] = R"reST(The ``return_typestate`` attribute can be applied to functions or parameters.
7314	When applied to a function the attribute specifies the state of the returned
7315	value. The function's body is checked to ensure that it always returns a value
7316	in the specified state. On the caller side, values returned by the annotated
7317	function are initialized to the given state.
7318
7319	When applied to a function parameter it modifies the state of an argument after
7320	a call to the function returns. The function's body is checked to ensure that
7321	the parameter is in the expected state before returning.)reST";
7322
7323	static const char AttrDoc_ReturnsNonNull[] = R"reST(The ``returns_nonnull`` attribute indicates that a particular function (or
7324	Objective-C method) always returns a non-null pointer. For example, a
7325	particular system ``malloc`` might be defined to terminate a process when
7326	memory is not available rather than returning a null pointer:
7327
7328	.. code-block:: c
7329
7330	extern void * malloc (size_t size) __attribute__((returns_nonnull));
7331
7332	The ``returns_nonnull`` attribute implies that returning a null pointer is
7333	undefined behavior, which the optimizer may take advantage of. The ``_Nonnull``
7334	type qualifier indicates that a pointer cannot be null in a more general manner
7335	(because it is part of the type system) and does not imply undefined behavior,
7336	making it more widely applicable)reST";
7337
7338	static const char AttrDoc_ReturnsTwice[] = R"reST(No documentation.)reST";
7339
7340	static const char AttrDoc_RootSignature[] = R"reST(The ``RootSignature`` attribute applies to HLSL entry functions to define what
7341	types of resources are bound to the graphics pipeline.
7342
7343	For details about the use and specification of Root Signatures please see here:
7344	https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signatures)reST";
7345
7346	static const char AttrDoc_SPtr[] = R"reST(The ``__sptr`` qualifier specifies that a 32-bit pointer should be sign
7347	extended when converted to a 64-bit pointer.)reST";
7348
7349	static const char AttrDoc_SYCLExternal[] = R"reST(The ``sycl_external`` attribute indicates that a function defined in another
7350	translation unit may be called by a device function defined in the current
7351	translation unit or, if defined in the current translation unit, the function
7352	may be called by device functions defined in other translation units.
7353	The attribute is intended for use in the implementation of the ``SYCL_EXTERNAL``
7354	macro as specified in section 5.10.1, "SYCL functions and member functions
7355	linkage", of the SYCL 2020 specification.
7356
7357	The attribute only appertains to functions and only those that meet the
7358	following requirements:
7359
7360	* Has external linkage
7361	* Is not explicitly defined as deleted (the function may be an explicitly
7362	defaulted function that is defined as deleted)
7363
7364	The attribute shall be present on the first declaration of a function and
7365	may optionally be present on subsequent declarations.
7366
7367	When compiling for a SYCL device target that does not support the generic
7368	address space, the function shall not specify a raw pointer or reference type
7369	as the return type or as a parameter type.
7370	See section 5.10, "SYCL offline linking", of the SYCL 2020 specification.
7371	The following examples demonstrate the use of this attribute:
7372
7373	.. code-block:: c++
7374
7375	[[clang::sycl_external]] void Foo(); // Ok.
7376
7377	[[clang::sycl_external]] void Bar() { /* ... */ } // Ok.
7378
7379	[[clang::sycl_external]] extern void Baz(); // Ok.
7380
7381	[[clang::sycl_external]] static void Quux() { /* ... */ } // error: Quux() has internal linkage.)reST";
7382
7383	static const char AttrDoc_SYCLKernel[] = R"reST(The ``sycl_kernel`` attribute specifies that a function template will be used
7384	to outline device code and to generate an OpenCL kernel.
7385	Here is a code example of the SYCL program, which demonstrates the compiler's
7386	outlining job:
7387
7388	.. code-block:: c++
7389
7390	int foo(int x) { return ++x; }
7391
7392	using namespace cl::sycl;
7393	queue Q;
7394	buffer<int, 1> a(range<1>{1024});
7395	Q.submit([&](handler& cgh) {
7396	auto A = a.get_access<access::mode::write>(cgh);
7397	cgh.parallel_for<init_a>(range<1>{1024}, [=](id<1> index) {
7398	A[index] = index[0] + foo(42);
7399	});
7400	}
7401
7402	A C++ function object passed to the ``parallel_for`` is called a "SYCL kernel".
7403	A SYCL kernel defines the entry point to the "device part" of the code. The
7404	compiler will emit all symbols accessible from a "kernel". In this code
7405	example, the compiler will emit "foo" function. More details about the
7406	compilation of functions for the device part can be found in the SYCL 1.2.1
7407	specification Section 6.4.
7408	To show to the compiler entry point to the "device part" of the code, the SYCL
7409	runtime can use the ``sycl_kernel`` attribute in the following way:
7410
7411	.. code-block:: c++
7412
7413	namespace cl {
7414	namespace sycl {
7415	class handler {
7416	template <typename KernelName, typename KernelType/, .../>
7417	__attribute__((sycl_kernel)) void sycl_kernel_function(KernelType KernelFuncObj) {
7418	// ...
7419	KernelFuncObj();
7420	}
7421
7422	template <typename KernelName, typename KernelType, int Dims>
7423	void parallel_for(range<Dims> NumWorkItems, KernelType KernelFunc) {
7424	#ifdef __SYCL_DEVICE_ONLY__
7425	sycl_kernel_function<KernelName, KernelType, Dims>(KernelFunc);
7426	#else
7427	// Host implementation
7428	#endif
7429	}
7430	};
7431	} // namespace sycl
7432	} // namespace cl
7433
7434	The compiler will also generate an OpenCL kernel using the function marked with
7435	the ``sycl_kernel`` attribute.
7436	Here is the list of SYCL device compiler expectations with regard to the
7437	function marked with the ``sycl_kernel`` attribute:
7438
7439	- The function must be a template with at least two type template parameters.
7440	The compiler generates an OpenCL kernel and uses the first template parameter
7441	as a unique name for the generated OpenCL kernel. The host application uses
7442	this unique name to invoke the OpenCL kernel generated for the SYCL kernel
7443	specialized by this name and second template parameter ``KernelType`` (which
7444	might be an unnamed function object type).
7445	- The function must have at least one parameter. The first parameter is
7446	required to be a function object type (named or unnamed i.e. lambda). The
7447	compiler uses function object type fields to generate OpenCL kernel
7448	parameters.
7449	- The function must return void. The compiler reuses the body of marked functions to
7450	generate the OpenCL kernel body, and the OpenCL kernel must return ``void``.
7451
7452	The SYCL kernel in the previous code sample meets these expectations.)reST";
7453
7454	static const char AttrDoc_SYCLKernelEntryPoint[] = R"reST(The ``sycl_kernel_entry_point`` attribute facilitates the launch of a SYCL
7455	kernel and the generation of an offload kernel entry point, sometimes called
7456	a SYCL kernel caller function, suitable for invoking a SYCL kernel on an
7457	offload device. The attribute is intended for use in the implementation of
7458	SYCL kernel invocation functions like the ``single_task`` and ``parallel_for``
7459	member functions of the ``sycl::handler`` class specified in section 4.9.4,
7460	"Command group ``handler`` class", of the SYCL 2020 specification.
7461
7462	The attribute requires a single type argument that meets the requirements for
7463	a SYCL kernel name as described in section 5.2, "Naming of kernels", of the
7464	SYCL 2020 specification. A unique kernel name type is required for each
7465	function declared with the attribute. The attribute may not first appear on a
7466	declaration that follows a definition of the function.
7467
7468	The attribute only appertains to functions and only those that meet the
7469	following requirements.
7470
7471	* Has a non-deduced ``void`` return type.
7472	* Is not a constructor or destructor.
7473	* Is not a non-static member function with an explicit object parameter.
7474	* Is not a C variadic function.
7475	* Is not a coroutine.
7476	* Is not defined as deleted or as defaulted.
7477	* Is not defined with a function try block.
7478	* Is not declared with the ``constexpr`` or ``consteval`` specifiers.
7479	* Is not declared with the ``[[noreturn]]`` attribute.
7480
7481	Use in the implementation of a SYCL kernel invocation function might look as
7482	follows.
7483
7484	.. code-block:: c++
7485
7486	namespace sycl {
7487	class handler {
7488	template<typename KernelName, typename... Ts>
7489	void sycl_kernel_launch(const char* kernelSymbol, Ts&&... kernelArgs) {
7490	// This code will run on the host and is responsible for calling functions
7491	// appropriate for the desired offload backend (OpenCL, CUDA, HIP,
7492	// Level Zero, etc...) to copy the kernel arguments denoted by kernelArgs
7493	// to a device and to schedule an invocation of the offload kernel entry
7494	// point denoted by kernelSymbol with the copied arguments.
7495	}
7496
7497	template<typename KernelName, typename KernelType>
7498	[[ clang::sycl_kernel_entry_point(KernelName) ]]
7499	void kernel_entry_point(KernelType kernelFunc) {
7500	// This code will run on the device. The call to kernelFunc() invokes
7501	// the SYCL kernel.
7502	kernelFunc();
7503	}
7504
7505	public:
7506	template<typename KernelName, typename KernelType>
7507	void single_task(const KernelType& kernelFunc) {
7508	// This code will run on the host. kernel_entry_point() is called to
7509	// trigger generation of an offload kernel entry point and to schedule
7510	// an invocation of it on a device with kernelFunc (a SYCL kernel object)
7511	// passed as a kernel argument. This call will result in an implicit call
7512	// to sycl_kernel_launch() with the symbol name for the generated offload
7513	// kernel entry point passed as the first function argument followed by
7514	// kernelFunc.
7515	kernel_entry_point<KernelName>(kernelFunc);
7516	}
7517	};
7518	} // namespace sycl
7519
7520	A SYCL kernel object is a callable object of class type that is constructed on
7521	a host, often via a lambda expression, and then passed to a SYCL kernel
7522	invocation function to be executed on an offload device. The ``kernelFunc``
7523	parameters in the example code above correspond to SYCL kernel objects.
7524
7525	A SYCL kernel object type is required to satisfy the device copyability
7526	requirements specified in section 3.13.1, "Device copyable", of the SYCL 2020
7527	specification. Additionally, any data members of the kernel object type are
7528	required to satisfy section 4.12.4, "Rules for parameter passing to kernels".
7529	For most types, these rules require that the type is trivially copyable.
7530	However, the SYCL specification mandates that certain special SYCL types, such
7531	as ``sycl::accessor`` and ``sycl::stream``, be device copyable even if they are
7532	not trivially copyable. These types require special handling because they cannot
7533	necessarily be copied to device memory as if by ``memcpy()``.
7534
7535	The SYCL kernel object and its data members constitute the parameters of an
7536	offload kernel. An offload kernel consists of an offload entry point function
7537	and the set of all functions and variables that are directly or indirectly used
7538	by the entry point function.
7539
7540	A SYCL kernel invocation function is responsible for performing the following
7541	tasks (likely with the help of an offload backend like OpenCL):
7542
7543	#. Identifying the offload kernel entry point to be used for the SYCL kernel.
7544
7545	#. Validating that the SYCL kernel object type and its data members meet the
7546	SYCL device copyability and kernel parameter requirements noted above.
7547
7548	#. Copying the SYCL kernel object and any other kernel arguments to device
7549	memory including any special handling required for SYCL special types.
7550
7551	#. Initiating execution of the offload kernel entry point.
7552
7553	The offload kernel entry point for a SYCL kernel performs the following tasks:
7554
7555	#. Calling the ``operator()`` member function of the SYCL kernel object.
7556
7557	The ``sycl_kernel_entry_point`` attribute facilitates or automates these tasks
7558	by providing generation of an offload kernel entry point with a unique symbol
7559	name, type checking of kernel argument requirements, and initiation of kernel
7560	execution via synthesized calls to a ``sycl_kernel_launch`` template.
7561
7562	A function declared with the ``sycl_kernel_entry_point`` attribute specifies
7563	the parameters and body of an offload entry point function. Consider the
7564	following call to the ``single_task()`` SYCL kernel invocation function assuming
7565	an implementation similar to the one shown above.
7566
7567	.. code-block:: c++
7568
7569	struct S { int i; };
7570	void f(sycl::handler &handler, sycl::stream &sout, S s) {
7571	handler.single_task<struct KN>([=] {
7572	sout << "The value of s.i is " << s.i << "\n";
7573	});
7574	}
7575
7576	The SYCL kernel object is the result of the lambda expression. The call to
7577	``kernel_entry_point()`` via the call to ``single_task()`` triggers the
7578	generation of an offload kernel entry point function that looks approximately
7579	as follows.
7580
7581	.. code-block:: c++
7582
7583	void sycl-kernel-caller-for-KN(kernel-type kernelFunc) {
7584	kernelFunc();
7585	}
7586
7587	There are a few items worthy of note:
7588
7589	#. ``sycl-kernel-caller-for-KN`` is an exposition only name; the actual name
7590	generated for an entry point is an implementation detail and subject to
7591	change. However, the name will incorporate the SYCL kernel name, ``KN``,
7592	that was passed as the ``KernelName`` template parameter to
7593	``single_task()`` and eventually provided as the argument to the
7594	``sycl_kernel_entry_point`` attribute in order to ensure that a unique
7595	name is generated for each entry point. There is a one-to-one correspondence
7596	between SYCL kernel names and offload kernel entry points.
7597
7598	#. The SYCL kernel is a lambda closure type and therefore has no name;
7599	``kernel-type`` is substituted above and corresponds to the ``KernelType``
7600	template parameter deduced in the call to ``single_task()``.
7601
7602	#. The parameter and the call to ``kernelFunc()`` in the function body
7603	correspond to the definition of ``kernel_entry_point()`` as called by
7604	``single_task()``.
7605
7606	#. The parameter is type checked for conformance with the SYCL device
7607	copyability and kernel parameter requirements.
7608
7609	Within ``single_task()``, the call to ``kernel_entry_point()`` is effectively
7610	replaced with a synthesized call to a ''sycl_kernel_launch`` template that
7611	looks approximately as follows.
7612
7613	.. code-block:: c++
7614
7615	sycl_kernel_launch<KN>("sycl-kernel-caller-for-KN", kernelFunc);
7616
7617	There are a few items worthy of note:
7618
7619	#. Lookup for the ``sycl_kernel_launch`` template is performed as if from the
7620	body of the (possibly instantiated) definition of ``kernel_entry_point()``.
7621	If name lookup or overload resolution fails, the program is ill-formed.
7622	If the selected overload is a non-static member function, then ``this`` is
7623	passed as the implicit object parameter.
7624
7625	#. Function arguments passed to ``sycl_kernel_launch()`` are passed
7626	as if by ``std::move(x)``.
7627
7628	#. The ``sycl_kernel_launch`` template is expected to be provided by the SYCL
7629	library implementation. It is responsible for copying the kernel arguments
7630	to device memory and for scheduling execution of the generated offload
7631	kernel entry point identified by the symbol name passed as the first
7632	function argument. ``sycl-kernel-caller-for-KN`` is substituted above for
7633	the actual symbol name that would be generated for the offload kernel entry
7634	point.
7635
7636	It is not necessary for a function declared with the ``sycl_kernel_entry_point``
7637	attribute to be called for the offload kernel entry point to be emitted. For
7638	inline functions and function templates, any ODR-use will suffice. For other
7639	functions, an ODR-use is not required; the offload kernel entry point will be
7640	emitted if the function is defined. In any case, a call to the function is
7641	required for the synthesized call to ``sycl_kernel_launch()`` to occur.
7642
7643	A function declared with the ``sycl_kernel_entry_point`` attribute may include
7644	an exception specification. If a non-throwing exception specification is
7645	present, an exception propagating from the implicit call to the
7646	``sycl_kernel_launch`` template will result in a call to ``std::terminate()``.
7647	Otherwise, such an exception will propagate normally.
7648
7649	Functions declared with the ``sycl_kernel_entry_point`` attribute are not
7650	limited to the simple example shown above. They may have additional template
7651	parameters, declare additional function parameters, and have complex control
7652	flow in the function body. The function must abide by the language feature
7653	restrictions described in section 5.4, "Language restrictions for device
7654	functions" in the SYCL 2020 specification. If the function is a non-static
7655	member function, ``this`` shall not be used in a potentially evaluated
7656	expression.)reST";
7657
7658	static const char AttrDoc_SYCLSpecialClass[] = R"reST(SYCL defines some special classes (accessor, sampler, and stream) which require
7659	specific handling during the generation of the SPIR entry point.
7660	The ``__attribute__((sycl_special_class))`` attribute is used in SYCL
7661	headers to indicate that a class or a struct needs a specific handling when
7662	it is passed from host to device.
7663	Special classes will have a mandatory ``__init`` method and an optional
7664	``__finalize`` method (the ``__finalize`` method is used only with the
7665	``stream`` type). Kernel parameters types are extract from the ``__init`` method
7666	parameters. The kernel function arguments list is derived from the
7667	arguments of the ``__init`` method. The arguments of the ``__init`` method are
7668	copied into the kernel function argument list and the ``__init`` and
7669	``__finalize`` methods are called at the beginning and the end of the kernel,
7670	respectively.
7671	The ``__init`` and ``__finalize`` methods must be defined inside the
7672	special class.
7673	Please note that this is an attribute that is used as an internal
7674	implementation detail and not intended to be used by external users.
7675
7676	The syntax of the attribute is as follows:
7677
7678	.. code-block:: text
7679
7680	class __attribute__((sycl_special_class)) accessor {};
7681	class [[clang::sycl_special_class]] accessor {};
7682
7683	This is a code example that illustrates the use of the attribute:
7684
7685	.. code-block:: c++
7686
7687	class __attribute__((sycl_special_class)) SpecialType {
7688	int F1;
7689	int F2;
7690	void __init(int f1) {
7691	F1 = f1;
7692	F2 = f1;
7693	}
7694	void __finalize() {}
7695	public:
7696	SpecialType() = default;
7697	int getF2() const { return F2; }
7698	};
7699
7700	int main () {
7701	SpecialType T;
7702	cgh.single_task([=] {
7703	T.getF2();
7704	});
7705	}
7706
7707	This would trigger the following kernel entry point in the AST:
7708
7709	.. code-block:: c++
7710
7711	void __sycl_kernel(int f1) {
7712	SpecialType T;
7713	T.__init(f1);
7714	...
7715	T.__finalize()
7716	})reST";
7717
7718	static const char AttrDoc_ScopedLockable[] = R"reST(No documentation.)reST";
7719
7720	static const char AttrDoc_Section[] = R"reST(The ``section`` attribute allows you to specify a specific section a
7721	global variable or function should be in after translation.)reST";
7722
7723	static const char AttrDoc_SelectAny[] = R"reST(This attribute appertains to a global symbol, causing it to have a weak
7724	definition (
7725	`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
7726	), allowing the linker to select any definition.
7727
7728	For more information see
7729	`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
7730	or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.)reST";
7731
7732	static const char AttrDoc_Sentinel[] = R"reST(No documentation.)reST";
7733
7734	static const char AttrDoc_SetTypestate[] = R"reST(Annotate methods that transition an object into a new state with
7735	``__attribute__((set_typestate(new_state)))``. The new state must be
7736	unconsumed, consumed, or unknown.)reST";
7737
7738	static const char AttrDoc_SizedBy[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
7739	structure in C. The argument for the attribute is the name of a field member
7740	holding the count of elements in the flexible array. This information can be
7741	used to improve the results of the array bound sanitizer and the
7742	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
7743	within the same non-anonymous, enclosing struct as the flexible array member.
7744
7745	This example specifies that the flexible array member ``array`` has the number
7746	of elements allocated for it in ``count``:
7747
7748	.. code-block:: c
7749
7750	struct bar;
7751
7752	struct foo {
7753	size_t count;
7754	char other;
7755	struct bar *array[] __attribute__((counted_by(count)));
7756	};
7757
7758	This establishes a relationship between ``array`` and ``count``. Specifically,
7759	``array`` must have at least ``count`` number of elements available. It's the
7760	user's responsibility to ensure that this relationship is maintained through
7761	changes to the structure.
7762
7763	In the following example, the allocated array erroneously has fewer elements
7764	than what's specified by ``p->count``. This would result in an out-of-bounds
7765	access not being detected.
7766
7767	.. code-block:: c
7768
7769	#define SIZE_INCR 42
7770
7771	struct foo *p;
7772
7773	void foo_alloc(size_t count) {
7774	p = malloc(MAX(sizeof(struct foo),
7775	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7776	p->count = count + SIZE_INCR;
7777	}
7778
7779	The next example updates ``p->count``, but breaks the relationship requirement
7780	that ``p->array`` must have at least ``p->count`` number of elements available:
7781
7782	.. code-block:: c
7783
7784	#define SIZE_INCR 42
7785
7786	struct foo *p;
7787
7788	void foo_alloc(size_t count) {
7789	p = malloc(MAX(sizeof(struct foo),
7790	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7791	p->count = count;
7792	}
7793
7794	void use_foo(int index, int val) {
7795	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
7796	p->array[index] = val; /* The sanitizer can't properly check this access. */
7797	}
7798
7799	In this example, an update to ``p->count`` maintains the relationship
7800	requirement:
7801
7802	.. code-block:: c
7803
7804	void use_foo(int index, int val) {
7805	if (p->count == 0)
7806	return;
7807	--p->count;
7808	p->array[index] = val;
7809	})reST";
7810
7811	static const char AttrDoc_SizedByOrNull[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
7812	structure in C. The argument for the attribute is the name of a field member
7813	holding the count of elements in the flexible array. This information can be
7814	used to improve the results of the array bound sanitizer and the
7815	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
7816	within the same non-anonymous, enclosing struct as the flexible array member.
7817
7818	This example specifies that the flexible array member ``array`` has the number
7819	of elements allocated for it in ``count``:
7820
7821	.. code-block:: c
7822
7823	struct bar;
7824
7825	struct foo {
7826	size_t count;
7827	char other;
7828	struct bar *array[] __attribute__((counted_by(count)));
7829	};
7830
7831	This establishes a relationship between ``array`` and ``count``. Specifically,
7832	``array`` must have at least ``count`` number of elements available. It's the
7833	user's responsibility to ensure that this relationship is maintained through
7834	changes to the structure.
7835
7836	In the following example, the allocated array erroneously has fewer elements
7837	than what's specified by ``p->count``. This would result in an out-of-bounds
7838	access not being detected.
7839
7840	.. code-block:: c
7841
7842	#define SIZE_INCR 42
7843
7844	struct foo *p;
7845
7846	void foo_alloc(size_t count) {
7847	p = malloc(MAX(sizeof(struct foo),
7848	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7849	p->count = count + SIZE_INCR;
7850	}
7851
7852	The next example updates ``p->count``, but breaks the relationship requirement
7853	that ``p->array`` must have at least ``p->count`` number of elements available:
7854
7855	.. code-block:: c
7856
7857	#define SIZE_INCR 42
7858
7859	struct foo *p;
7860
7861	void foo_alloc(size_t count) {
7862	p = malloc(MAX(sizeof(struct foo),
7863	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7864	p->count = count;
7865	}
7866
7867	void use_foo(int index, int val) {
7868	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
7869	p->array[index] = val; /* The sanitizer can't properly check this access. */
7870	}
7871
7872	In this example, an update to ``p->count`` maintains the relationship
7873	requirement:
7874
7875	.. code-block:: c
7876
7877	void use_foo(int index, int val) {
7878	if (p->count == 0)
7879	return;
7880	--p->count;
7881	p->array[index] = val;
7882	})reST";
7883
7884	static const char AttrDoc_SpeculativeLoadHardening[] = R"reST(This attribute can be applied to a function declaration in order to indicate
7885	that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
7886	should be enabled for the function body. This can also be applied to a method
7887	in Objective C. This attribute will take precedence over the command line flag in
7888	the case where `-mno-speculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
7889
7890	Speculative Load Hardening is a best-effort mitigation against
7891	information leak attacks that make use of control flow
7892	miss-speculation - specifically miss-speculation of whether a branch
7893	is taken or not. Typically vulnerabilities enabling such attacks are
7894	classified as "Spectre variant #1". Notably, this does not attempt to
7895	mitigate against miss-speculation of branch target, classified as
7896	"Spectre variant #2" vulnerabilities.
7897
7898	When inlining, the attribute is sticky. Inlining a function that
7899	carries this attribute will cause the caller to gain the
7900	attribute. This is intended to provide a maximally conservative model
7901	where the code in a function annotated with this attribute will always
7902	(even after inlining) end up hardened.)reST";
7903
7904	static const char AttrDoc_StackProtectorIgnore[] = R"reST(The ``stack_protector_ignore`` attribute skips analysis of the given local
7905	variable when determining if a function should use a stack protector.
7906
7907	The ``-fstack-protector`` option uses a heuristic to only add stack protectors
7908	to functions which contain variables or buffers over some size threshold. This
7909	attribute overrides that heuristic for the attached variable, opting
7910	them out. If this results in no variables or buffers remaining over the stack
7911	protector threshold, then the function will no longer use a stack protector.)reST";
7912
7913	static const char AttrDoc_StandaloneDebug[] = R"reST(The ``standalone_debug`` attribute causes debug info to be emitted for a record
7914	type regardless of the debug info optimizations that are enabled with
7915	-fno-standalone-debug. This attribute only has an effect when debug info
7916	optimizations are enabled (e.g. with -fno-standalone-debug), and is C++-only.)reST";
7917
7918	static const char AttrDoc_StdCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
7919	function to clear parameters off of the stack on return. This convention does
7920	not support variadic calls or unprototyped functions in C, and has no effect on
7921	x86_64 targets. This calling convention is used widely by the Windows API and
7922	COM applications. See the documentation for `__stdcall`_ on MSDN.
7923
7924	.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx)reST";
7925
7926	static const char AttrDoc_StrictFP[] = R"reST()reST";
7927
7928	static const char AttrDoc_StrictGuardStackCheck[] = R"reST(Clang supports the Microsoft style ``__declspec((strict_gs_check))`` attribute
7929	which upgrades the stack protector check from ``-fstack-protector`` to
7930	``-fstack-protector-strong``.
7931
7932	For example, it upgrades the stack protector for the function ``foo`` to
7933	``-fstack-protector-strong`` but function ``bar`` will still be built with the
7934	stack protector with the ``-fstack-protector`` option.
7935
7936	.. code-block:: c
7937
7938	__declspec((strict_gs_check))
7939	int foo(int x); // stack protection will be upgraded for foo.
7940
7941	int bar(int y); // bar can be built with the standard stack protector checks.)reST";
7942
7943	static const char AttrDoc_Suppress[] = R"reST(The ``suppress`` attribute suppresses unwanted warnings coming from static
7944	analysis tools such as the Clang Static Analyzer. The tool will not report
7945	any issues in source code annotated with the attribute.
7946
7947	The attribute cannot be used to suppress traditional Clang warnings, because
7948	many such warnings are emitted before the attribute is fully parsed.
7949	Consider using ``#pragma clang diagnostic`` to control such diagnostics,
7950	as described in `Controlling Diagnostics via Pragmas
7951	<https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas>`_.
7952
7953	The ``suppress`` attribute can be placed on an individual statement in order to
7954	suppress warnings about undesirable behavior occurring at that statement:
7955
7956	.. code-block:: c++
7957
7958	int foo() {
7959	int *x = nullptr;
7960	...
7961	[[clang::suppress]]
7962	return *x; // null pointer dereference warning suppressed here
7963	}
7964
7965	Putting the attribute on a compound statement suppresses all warnings in scope:
7966
7967	.. code-block:: c++
7968
7969	int foo() {
7970	[[clang::suppress]] {
7971	int *x = nullptr;
7972	...
7973	return *x; // warnings suppressed in the entire scope
7974	}
7975	}
7976
7977	The attribute can also be placed on entire declarations of functions, classes,
7978	variables, member variables, and so on, to suppress warnings related
7979	to the declarations themselves. When used this way, the attribute additionally
7980	suppresses all warnings in the lexical scope of the declaration:
7981
7982	.. code-block:: c++
7983
7984	class [[clang::suppress]] C {
7985	int foo() {
7986	int *x = nullptr;
7987	...
7988	return *x; // warnings suppressed in the entire class scope
7989	}
7990
7991	int bar();
7992	};
7993
7994	int C::bar() {
7995	int *x = nullptr;
7996	...
7997	return *x; // warning NOT suppressed! - not lexically nested in 'class C{}'
7998	}
7999
8000	Some static analysis warnings are accompanied by one or more notes, and the
8001	line of code against which the warning is emitted isn't necessarily the best
8002	for suppression purposes. In such cases the tools are allowed to implement
8003	additional ways to suppress specific warnings based on the attribute attached
8004	to a note location.
8005
8006	For example, the Clang Static Analyzer suppresses memory leak warnings when
8007	the suppression attribute is placed at the allocation site (highlited by
8008	a "note: memory is allocated"), which may be different from the line of code
8009	at which the program "loses track" of the pointer (where the warning
8010	is ultimately emitted):
8011
8012	.. code-block:: c
8013
8014	int bar1(bool coin_flip) {
8015	__attribute__((suppress))
8016	int result = (int )malloc(sizeof(int));
8017	if (coin_flip)
8018	return 1; // warning about this leak path is suppressed
8019
8020	return *result; // warning about this leak path is also suppressed
8021	}
8022
8023	int bar2(bool coin_flip) {
8024	int result = (int )malloc(sizeof(int));
8025	if (coin_flip)
8026	return 1; // leak warning on this path NOT suppressed
8027
8028	__attribute__((suppress))
8029	return *result; // leak warning is suppressed only on this path
8030	}
8031
8032
8033	When written as ``[[gsl::suppress]]``, this attribute suppresses specific
8034	clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
8035	way. The attribute can be attached to declarations, statements, and at
8036	namespace scope.
8037
8038	.. code-block:: c++
8039
8040	[[gsl::suppress("Rh-public")]]
8041	void f_() {
8042	int *p;
8043	[[gsl::suppress("type")]] {
8044	p = reinterpret_cast<int*>(7);
8045	}
8046	}
8047	namespace N {
8048	[[clang::suppress("type", "bounds")]];
8049	...
8050	}
8051
8052	.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement)reST";
8053
8054	static const char AttrDoc_SwiftAsync[] = R"reST(The ``swift_async`` attribute specifies if and how a particular function or
8055	Objective-C method is imported into a swift async method. For instance:
8056
8057	.. code-block:: objc
8058
8059	@interface MyClass : NSObject
8060	-(void)notActuallyAsync:(int)p1 withCompletionHandler:(void (^)())handler
8061	__attribute__((swift_async(none)));
8062
8063	-(void)actuallyAsync:(int)p1 callThisAsync:(void (^)())fun
8064	__attribute__((swift_async(swift_private, 1)));
8065	@end
8066
8067	Here, ``notActuallyAsync:withCompletionHandler`` would have been imported as
8068	``async`` (because it's last parameter's selector piece is
8069	``withCompletionHandler``) if not for the ``swift_async(none)`` attribute.
8070	Conversely, ``actuallyAsync:callThisAsync`` wouldn't have been imported as
8071	``async`` if not for the ``swift_async`` attribute because it doesn't match the
8072	naming convention.
8073
8074	When using ``swift_async`` to enable importing, the first argument to the
8075	attribute is either ``swift_private`` or ``not_swift_private`` to indicate
8076	whether the function/method is private to the current framework, and the second
8077	argument is the index of the completion handler parameter.)reST";
8078
8079	static const char AttrDoc_SwiftAsyncCall[] = R"reST(The ``swiftasynccall`` attribute indicates that a function is
8080	compatible with the low-level conventions of Swift async functions,
8081	provided it declares the right formal arguments.
8082
8083	In most respects, this is similar to the ``swiftcall`` attribute, except for
8084	the following:
8085
8086	- A parameter may be marked ``swift_async_context``, ``swift_context``
8087	or ``swift_indirect_result`` (with the same restrictions on parameter
8088	ordering as ``swiftcall``) but the parameter attribute
8089	``swift_error_result`` is not permitted.
8090
8091	- A ``swiftasynccall`` function must have return type ``void``.
8092
8093	- Within a ``swiftasynccall`` function, a call to a ``swiftasynccall``
8094	function that is the immediate operand of a ``return`` statement is
8095	guaranteed to be performed as a tail call. This syntax is allowed even
8096	in C as an extension (a call to a void-returning function cannot be a
8097	return operand in standard C). If something in the calling function would
8098	semantically be performed after a guaranteed tail call, such as the
8099	non-trivial destruction of a local variable or temporary,
8100	then the program is ill-formed.
8101
8102	Query for this attribute with ``__has_attribute(swiftasynccall)``. Query if
8103	the target supports the calling convention with
8104	``__has_extension(swiftasynccc)``.)reST";
8105
8106	static const char AttrDoc_SwiftAsyncContext[] = R"reST(The ``swift_async_context`` attribute marks a parameter of a ``swiftasynccall``
8107	function as having the special asynchronous context-parameter ABI treatment.
8108
8109	If the function is not ``swiftasynccall``, this attribute only generates
8110	extended frame information.
8111
8112	A context parameter must have pointer or reference type.)reST";
8113
8114	static const char AttrDoc_SwiftAsyncError[] = R"reST(The ``swift_async_error`` attribute specifies how an error state will be
8115	represented in a swift async method. It's a bit analogous to the ``swift_error``
8116	attribute for the generated async method. The ``swift_async_error`` attribute
8117	can indicate a variety of different ways of representing an error.
8118
8119	- ``__attribute__((swift_async_error(zero_argument, N)))``, specifies that the
8120	async method is considered to have failed if the Nth argument to the
8121	completion handler is zero.
8122
8123	- ``__attribute__((swift_async_error(nonzero_argument, N)))``, specifies that
8124	the async method is considered to have failed if the Nth argument to the
8125	completion handler is non-zero.
8126
8127	- ``__attribute__((swift_async_error(nonnull_error)))``, specifies that the
8128	async method is considered to have failed if the ``NSError *`` argument to the
8129	completion handler is non-null.
8130
8131	- ``__attribute__((swift_async_error(none)))``, specifies that the async method
8132	cannot fail.
8133
8134
8135	For instance:
8136
8137	.. code-block:: objc
8138
8139	@interface MyClass : NSObject
8140	-(void)asyncMethod:(void (^)(char, int, float))handler
8141	__attribute__((swift_async(swift_private, 1)))
8142	__attribute__((swift_async_error(zero_argument, 2)));
8143	@end
8144
8145	Here, the ``swift_async`` attribute specifies that ``handler`` is the completion
8146	handler for this method, and the ``swift_async_error`` attribute specifies that
8147	the ``int`` parameter is the one that represents the error.)reST";
8148
8149	static const char AttrDoc_SwiftAsyncName[] = R"reST(The ``swift_async_name`` attribute provides the name of the ``async`` overload for
8150	the given declaration in Swift. If this attribute is absent, the name is
8151	transformed according to the algorithm built into the Swift compiler.
8152
8153	The argument is a string literal that contains the Swift name of the function or
8154	method. The name may be a compound Swift name. The function or method with such
8155	an attribute must have more than zero parameters, as its last parameter is
8156	assumed to be a callback that's eliminated in the Swift ``async`` name.
8157
8158	.. code-block:: objc
8159
8160	@interface URL
8161	+ (void) loadContentsFrom:(URL )url callback:(void (^)(NSData ))data __attribute__((__swift_async_name__("URL.loadContentsFrom(_:)")))
8162	@end)reST";
8163
8164	static const char AttrDoc_SwiftAttr[] = R"reST(The ``swift_attr`` provides a Swift-specific annotation for the declaration
8165	or type to which the attribute appertains to. It can be used on any declaration
8166	or type in Clang. This kind of annotation is ignored by Clang as it doesn't have any
8167	semantic meaning in languages supported by Clang. The Swift compiler can
8168	interpret these annotations according to its own rules when importing C or
8169	Objective-C declarations.)reST";
8170
8171	static const char AttrDoc_SwiftBridge[] = R"reST(The ``swift_bridge`` attribute indicates that the declaration to which the
8172	attribute appertains is bridged to the named Swift type.
8173
8174	.. code-block:: objc
8175
8176	__attribute__((__objc_root__))
8177	@interface Base
8178	- (instancetype)init;
8179	@end
8180
8181	__attribute__((__swift_bridge__("BridgedI")))
8182	@interface I : Base
8183	@end
8184
8185	In this example, the Objective-C interface ``I`` will be made available to Swift
8186	with the name ``BridgedI``. It would be possible for the compiler to refer to
8187	``I`` still in order to bridge the type back to Objective-C.)reST";
8188
8189	static const char AttrDoc_SwiftBridgedTypedef[] = R"reST(The ``swift_bridged_typedef`` attribute indicates that when the typedef to which
8190	the attribute appertains is imported into Swift, it should refer to the bridged
8191	Swift type (e.g. Swift's ``String``) rather than the Objective-C type as written
8192	(e.g. ``NSString``).
8193
8194	.. code-block:: objc
8195
8196	@interface NSString;
8197	typedef NSString *AliasedString __attribute__((__swift_bridged_typedef__));
8198
8199	extern void acceptsAliasedString(AliasedString _Nonnull parameter);
8200
8201	In this case, the function ``acceptsAliasedString`` will be imported into Swift
8202	as a function which accepts a ``String`` type parameter.)reST";
8203
8204	static const char AttrDoc_SwiftCall[] = R"reST(The ``swiftcall`` attribute indicates that a function should be called
8205	using the Swift calling convention for a function or function pointer.
8206
8207	The lowering for the Swift calling convention, as described by the Swift
8208	ABI documentation, occurs in multiple phases. The first, "high-level"
8209	phase breaks down the formal parameters and results into innately direct
8210	and indirect components, adds implicit parameters for the generic
8211	signature, and assigns the context and error ABI treatments to parameters
8212	where applicable. The second phase breaks down the direct parameters
8213	and results from the first phase and assigns them to registers or the
8214	stack. The ``swiftcall`` convention only handles this second phase of
8215	lowering; the C function type must accurately reflect the results
8216	of the first phase, as follows:
8217
8218	- Results classified as indirect by high-level lowering should be
8219	represented as parameters with the ``swift_indirect_result`` attribute.
8220
8221	- Results classified as direct by high-level lowering should be represented
8222	as follows:
8223
8224	- First, remove any empty direct results.
8225
8226	- If there are no direct results, the C result type should be ``void``.
8227
8228	- If there is one direct result, the C result type should be a type with
8229	the exact layout of that result type.
8230
8231	- If there are a multiple direct results, the C result type should be
8232	a struct type with the exact layout of a tuple of those results.
8233
8234	- Parameters classified as indirect by high-level lowering should be
8235	represented as parameters of pointer type.
8236
8237	- Parameters classified as direct by high-level lowering should be
8238	omitted if they are empty types; otherwise, they should be represented
8239	as a parameter type with a layout exactly matching the layout of the
8240	Swift parameter type.
8241
8242	- The context parameter, if present, should be represented as a trailing
8243	parameter with the ``swift_context`` attribute.
8244
8245	- The error result parameter, if present, should be represented as a
8246	trailing parameter (always following a context parameter) with the
8247	``swift_error_result`` attribute.
8248
8249	``swiftcall`` does not support variadic arguments or unprototyped functions.
8250
8251	The parameter ABI treatment attributes are aspects of the function type.
8252	A function type which applies an ABI treatment attribute to a
8253	parameter is a different type from an otherwise-identical function type
8254	that does not. A single parameter may not have multiple ABI treatment
8255	attributes.
8256
8257	Support for this feature is target-dependent, although it should be
8258	supported on every target that Swift supports. Query for this attribute
8259	with ``__has_attribute(swiftcall)``. Query if the target supports the
8260	calling convention with ``__has_extension(swiftcc)``. This implies
8261	support for the ``swift_context``, ``swift_error_result``, and
8262	``swift_indirect_result`` attributes.)reST";
8263
8264	static const char AttrDoc_SwiftContext[] = R"reST(The ``swift_context`` attribute marks a parameter of a ``swiftcall``
8265	or ``swiftasynccall`` function as having the special context-parameter
8266	ABI treatment.
8267
8268	This treatment generally passes the context value in a special register
8269	which is normally callee-preserved.
8270
8271	A ``swift_context`` parameter must either be the last parameter or must be
8272	followed by a ``swift_error_result`` parameter (which itself must always be
8273	the last parameter).
8274
8275	A context parameter must have pointer or reference type.)reST";
8276
8277	static const char AttrDoc_SwiftError[] = R"reST(The ``swift_error`` attribute controls whether a particular function (or
8278	Objective-C method) is imported into Swift as a throwing function, and if so,
8279	which dynamic convention it uses.
8280
8281	All of these conventions except ``none`` require the function to have an error
8282	parameter. Currently, the error parameter is always the last parameter of type
8283	``NSError*`` or ``CFErrorRef``. Swift will remove the error parameter from
8284	the imported API. When calling the API, Swift will always pass a valid address
8285	initialized to a null pointer.
8286
8287	* ``swift_error(none)`` means that the function should not be imported as
8288	throwing. The error parameter and result type will be imported normally.
8289
8290	* ``swift_error(null_result)`` means that calls to the function should be
8291	considered to have thrown if they return a null value. The return type must be
8292	a pointer type, and it will be imported into Swift with a non-optional type.
8293	This is the default error convention for Objective-C methods that return
8294	pointers.
8295
8296	* ``swift_error(zero_result)`` means that calls to the function should be
8297	considered to have thrown if they return a zero result. The return type must be
8298	an integral type. If the return type would have been imported as ``Bool``, it
8299	is instead imported as ``Void``. This is the default error convention for
8300	Objective-C methods that return a type that would be imported as ``Bool``.
8301
8302	* ``swift_error(nonzero_result)`` means that calls to the function should be
8303	considered to have thrown if they return a non-zero result. The return type must
8304	be an integral type. If the return type would have been imported as ``Bool``,
8305	it is instead imported as ``Void``.
8306
8307	* ``swift_error(nonnull_error)`` means that calls to the function should be
8308	considered to have thrown if they leave a non-null error in the error parameter.
8309	The return type is left unmodified.)reST";
8310
8311	static const char AttrDoc_SwiftErrorResult[] = R"reST(The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
8312	function as having the special error-result ABI treatment.
8313
8314	This treatment generally passes the underlying error value in and out of
8315	the function through a special register which is normally callee-preserved.
8316	This is modeled in C by pretending that the register is addressable memory:
8317
8318	- The caller appears to pass the address of a variable of pointer type.
8319	The current value of this variable is copied into the register before
8320	the call; if the call returns normally, the value is copied back into the
8321	variable.
8322
8323	- The callee appears to receive the address of a variable. This address
8324	is actually a hidden location in its own stack, initialized with the
8325	value of the register upon entry. When the function returns normally,
8326	the value in that hidden location is written back to the register.
8327
8328	A ``swift_error_result`` parameter must be the last parameter, and it must be
8329	preceded by a ``swift_context`` parameter.
8330
8331	A ``swift_error_result`` parameter must have type ``T*`` or ``T&`` for some
8332	type T. Note that no qualifiers are permitted on the intermediate level.
8333
8334	It is undefined behavior if the caller does not pass a pointer or
8335	reference to a valid object.
8336
8337	The standard convention is that the error value itself (that is, the
8338	value stored in the apparent argument) will be null upon function entry,
8339	but this is not enforced by the ABI.)reST";
8340
8341	static const char AttrDoc_SwiftImportAsNonGeneric[] = R"reST()reST";
8342
8343	static const char AttrDoc_SwiftImportPropertyAsAccessors[] = R"reST()reST";
8344
8345	static const char AttrDoc_SwiftIndirectResult[] = R"reST(The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
8346	or ``swiftasynccall`` function as having the special indirect-result ABI
8347	treatment.
8348
8349	This treatment gives the parameter the target's normal indirect-result
8350	ABI treatment, which may involve passing it differently from an ordinary
8351	parameter. However, only the first indirect result will receive this
8352	treatment. Furthermore, low-level lowering may decide that a direct result
8353	must be returned indirectly; if so, this will take priority over the
8354	``swift_indirect_result`` parameters.
8355
8356	A ``swift_indirect_result`` parameter must either be the first parameter or
8357	follow another ``swift_indirect_result`` parameter.
8358
8359	A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
8360	some object type ``T``. If ``T`` is a complete type at the point of
8361	definition of a function, it is undefined behavior if the argument
8362	value does not point to storage of adequate size and alignment for a
8363	value of type ``T``.
8364
8365	Making indirect results explicit in the signature allows C functions to
8366	directly construct objects into them without relying on language
8367	optimizations like C++'s named return value optimization (NRVO).)reST";
8368
8369	static const char AttrDoc_SwiftName[] = R"reST(The ``swift_name`` attribute provides the name of the declaration in Swift. If
8370	this attribute is absent, the name is transformed according to the algorithm
8371	built into the Swift compiler.
8372
8373	The argument is a string literal that contains the Swift name of the function,
8374	variable, or type. When renaming a function, the name may be a compound Swift
8375	name. For a type, enum constant, property, or variable declaration, the name
8376	must be a simple or qualified identifier.
8377
8378	.. code-block:: objc
8379
8380	@interface URL
8381	- (void) initWithString:(NSString *)s __attribute__((__swift_name__("URL.init(_:)")))
8382	@end
8383
8384	void __attribute__((__swift_name__("squareRoot()"))) sqrt(double v) {
8385	})reST";
8386
8387	static const char AttrDoc_SwiftNewType[] = R"reST(The ``swift_newtype`` attribute indicates that the typedef to which the
8388	attribute appertains is imported as a new Swift type of the typedef's name.
8389	Previously, the attribute was spelt ``swift_wrapper``. While the behaviour of
8390	the attribute is identical with either spelling, ``swift_wrapper`` is
8391	deprecated, only exists for compatibility purposes, and should not be used in
8392	new code.
8393
8394	* ``swift_newtype(struct)`` means that a Swift struct will be created for this
8395	typedef.
8396
8397	* ``swift_newtype(enum)`` means that a Swift enum will be created for this
8398	typedef.
8399
8400	.. code-block:: c
8401
8402	// Import UIFontTextStyle as an enum type, with enumerated values being
8403	// constants.
8404	typedef NSString * UIFontTextStyle __attribute__((__swift_newtype__(enum)));
8405
8406	// Import UIFontDescriptorFeatureKey as a structure type, with enumerated
8407	// values being members of the type structure.
8408	typedef NSString * UIFontDescriptorFeatureKey __attribute__((__swift_newtype__(struct)));)reST";
8409
8410	static const char AttrDoc_SwiftNullability[] = R"reST()reST";
8411
8412	static const char AttrDoc_SwiftObjCMembers[] = R"reST(This attribute indicates that Swift subclasses and members of Swift extensions
8413	of this class will be implicitly marked with the ``@objcMembers`` Swift
8414	attribute, exposing them back to Objective-C.)reST";
8415
8416	static const char AttrDoc_SwiftPrivate[] = R"reST(Declarations marked with the ``swift_private`` attribute are hidden from the
8417	framework client but are still made available for use within the framework or
8418	Swift SDK overlay.
8419
8420	The purpose of this attribute is to permit a more idomatic implementation of
8421	declarations in Swift while hiding the non-idiomatic one.)reST";
8422
8423	static const char AttrDoc_SwiftType[] = R"reST()reST";
8424
8425	static const char AttrDoc_SwiftVersionedAddition[] = R"reST()reST";
8426
8427	static const char AttrDoc_SwiftVersionedRemoval[] = R"reST()reST";
8428
8429	static const char AttrDoc_SysVABI[] = R"reST(On Windows x86_64 targets, this attribute changes the calling convention of a
8430	function to match the default convention used on Sys V targets such as Linux,
8431	Mac, and BSD. This attribute has no effect on other targets.)reST";
8432
8433	static const char AttrDoc_TLSModel[] = R"reST(The ``tls_model`` attribute allows you to specify which thread-local storage
8434	model to use. It accepts the following strings:
8435
8436	* global-dynamic
8437	* local-dynamic
8438	* initial-exec
8439	* local-exec
8440
8441	TLS models are mutually exclusive.)reST";
8442
8443	static const char AttrDoc_Target[] = R"reST(Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute.
8444	This attribute may be attached to a function definition and instructs
8445	the backend to use different code generation options than were passed on the
8446	command line.
8447
8448	The current set of options correspond to the existing "subtarget features" for
8449	the target with or without a "-mno-" in front corresponding to the absence
8450	of the feature, as well as ``arch="CPU"`` which will change the default "CPU"
8451	for the function.
8452
8453	For X86, the attribute also allows ``tune="CPU"`` to optimize the generated
8454	code for the given CPU without changing the available instructions.
8455
8456	For AArch64, ``arch="Arch"`` will set the architecture, similar to the -march
8457	command line options. ``cpu="CPU"`` can be used to select a specific cpu,
8458	as per the ``-mcpu`` option, similarly for ``tune=``. The attribute also allows the
8459	"branch-protection=<args>" option, where the permissible arguments and their
8460	effect on code generation are the same as for the command-line option
8461	``-mbranch-protection``.
8462
8463	Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
8464	"avx", "xop" and largely correspond to the machine specific options handled by
8465	the front end.
8466
8467	Note that this attribute does not apply transitively to nested functions such
8468	as blocks or C++ lambdas.
8469
8470	Additionally, this attribute supports function multiversioning for ELF based
8471	x86/x86-64 targets, which can be used to create multiple implementations of the
8472	same function that will be resolved at runtime based on the priority of their
8473	``target`` attribute strings. A function is considered a multiversioned function
8474	if either two declarations of the function have different ``target`` attribute
8475	strings, or if it has a ``target`` attribute string of ``default``. For
8476	example:
8477
8478	.. code-block:: c++
8479
8480	__attribute__((target("arch=atom")))
8481	void foo() {} // will be called on 'atom' processors.
8482	__attribute__((target("default")))
8483	void foo() {} // will be called on any other processors.
8484
8485	All multiversioned functions must contain a ``default`` (fallback)
8486	implementation, otherwise usages of the function are considered invalid.
8487	Additionally, a function may not become multiversioned after its first use.)reST";
8488
8489	static const char AttrDoc_TargetClones[] = R"reST(Clang supports the ``target_clones("OPTIONS")`` attribute. This attribute may be
8490	attached to a function declaration and causes function multiversioning, where
8491	multiple versions of the function will be emitted with different code
8492	generation options. Additionally, these versions will be resolved at runtime
8493	based on the priority of their attribute options. All ``target_clone`` functions
8494	are considered multiversioned functions.
8495
8496	For AArch64 target:
8497	The attribute contains comma-separated strings of target features joined by "+"
8498	sign. For example:
8499
8500	.. code-block:: c++
8501
8502	__attribute__((target_clones("sha2+memtag", "fcma+sve2-pmull128")))
8503	void foo() {}
8504
8505	For every multiversioned function a ``default`` (fallback) implementation
8506	always generated if not specified directly.
8507
8508	For x86/x86-64 targets:
8509	All multiversioned functions must contain a ``default`` (fallback)
8510	implementation, otherwise usages of the function are considered invalid.
8511	Additionally, a function may not become multiversioned after its first use.
8512
8513	The options to ``target_clones`` can either be a target-specific architecture
8514	(specified as ``arch=CPU``), or one of a list of subtarget features.
8515
8516	Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
8517	"avx", "xop" and largely correspond to the machine specific options handled by
8518	the front end.
8519
8520	The versions can either be listed as a comma-separated sequence of string
8521	literals or as a single string literal containing a comma-separated list of
8522	versions. For compatibility with GCC, the two formats can be mixed. For
8523	example, the following will emit 4 versions of the function:
8524
8525	.. code-block:: c++
8526
8527	__attribute__((target_clones("arch=atom,avx2","arch=ivybridge","default")))
8528	void foo() {}
8529
8530	For targets that support the GNU indirect function (IFUNC) feature, dispatch
8531	is performed by emitting an indirect function that is resolved to the appropriate
8532	target clone at load time. The indirect function is given the name the
8533	multiversioned function would have if it had been declared without the attribute.
8534	For backward compatibility with earlier Clang releases, a function alias with an
8535	``.ifunc`` suffix is also emitted. The ``.ifunc`` suffixed symbol is a deprecated
8536	feature and support for it may be removed in the future.
8537
8538	For PowerPC targets, ``target_clones`` is supported on AIX only. Only CPU
8539	(specified as ``cpu=CPU``) and ``default`` options are allowed. IFUNC is supported
8540	on AIX in Clang, so dispatch is implemented similar to other targets using IFUNC.
8541	An FMV function that is only declared in a translation unit is treated as a
8542	non-FMV. The resolver and the function clones are given internal linkage.)reST";
8543
8544	static const char AttrDoc_TargetVersion[] = R"reST(For AArch64 target clang supports function multiversioning by
8545	``__attribute__((target_version("OPTIONS")))`` attribute. When applied to a
8546	function it instructs compiler to emit multiple function versions based on
8547	``target_version`` attribute strings, which resolved at runtime depend on their
8548	priority and target features availability. One of the versions is always
8549	( implicitly or explicitly ) the ``default`` (fallback). Attribute strings can
8550	contain dependent features names joined by the "+" sign.
8551
8552	For targets that support the GNU indirect function (IFUNC) feature, dispatch
8553	is performed by emitting an indirect function that is resolved to the appropriate
8554	target clone at load time. The indirect function is given the name the
8555	multiversioned function would have if it had been declared without the attribute.
8556	For backward compatibility with earlier Clang releases, a function alias with an
8557	``.ifunc`` suffix is also emitted. The ``.ifunc`` suffixed symbol is a deprecated
8558	feature and support for it may be removed in the future.)reST";
8559
8560	static const char AttrDoc_TestTypestate[] = R"reST(Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
8561	returns true if the object is in the specified state..)reST";
8562
8563	static const char AttrDoc_ThisCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
8564	function to use ECX for the first parameter (typically the implicit ``this``
8565	parameter of C++ methods) and clear parameters off of the stack on return. This
8566	convention does not support variadic calls or unprototyped functions in C, and
8567	has no effect on x86_64 targets. See the documentation for `__thiscall`_ on
8568	MSDN.
8569
8570	.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx)reST";
8571
8572	static const char AttrDoc_Thread[] = R"reST(The ``__declspec(thread)`` attribute declares a variable with thread local
8573	storage. It is available under the ``-fms-extensions`` flag for MSVC
8574	compatibility. See the documentation for `__declspec(thread)`_ on MSDN.
8575
8576	.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
8577
8578	In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
8579	GNU ``__thread`` keyword. The variable must not have a destructor and must have
8580	a constant initializer, if any. The attribute only applies to variables
8581	declared with static storage duration, such as globals, class static data
8582	members, and static locals.)reST";
8583
8584	static const char AttrDoc_TransparentUnion[] = R"reST(This attribute can be applied to a union to change the behavior of calls to
8585	functions that have an argument with a transparent union type. The compiler
8586	behavior is changed in the following manner:
8587
8588	- A value whose type is any member of the transparent union can be passed as an
8589	argument without the need to cast that value.
8590
8591	- The argument is passed to the function using the calling convention of the
8592	first member of the transparent union. Consequently, all the members of the
8593	transparent union should have the same calling convention as its first member.
8594
8595	Transparent unions are not supported in C++.)reST";
8596
8597	static const char AttrDoc_TrivialABI[] = R"reST(The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
8598	It instructs the compiler to pass and return the type using the C ABI for the
8599	underlying type when the type would otherwise be considered non-trivial for the
8600	purpose of calls.
8601	A class annotated with ``trivial_abi`` can have non-trivial destructors or
8602	copy/move constructors without automatically becoming non-trivial for the
8603	purposes of calls. For example:
8604
8605	.. code-block:: c++
8606
8607	// A is trivial for the purposes of calls because ``trivial_abi`` makes the
8608	// user-provided special functions trivial.
8609	struct __attribute__((trivial_abi)) A {
8610	~A();
8611	A(const A &);
8612	A(A &&);
8613	int x;
8614	};
8615
8616	// B's destructor and copy/move constructor are considered trivial for the
8617	// purpose of calls because A is trivial.
8618	struct B {
8619	A a;
8620	};
8621
8622	If a type is trivial for the purposes of calls, has a non-trivial destructor,
8623	and is passed as an argument by value, the convention is that the callee will
8624	destroy the object before returning. The lifetime of the copy of the parameter
8625	in the caller ends without a destructor call when the call begins.
8626
8627	If a type is trivial for the purpose of calls, it is assumed to be trivially
8628	relocatable for the purpose of ``__is_trivially_relocatable`` and
8629	``__builtin_is_cpp_trivially_relocatable``.
8630	When a type marked with ``[[trivial_abi]]`` is used as a function argument,
8631	the compiler may omit the call to the copy constructor.
8632	Thus, side effects of the copy constructor are potentially not performed.
8633	For example, objects that contain pointers to themselves or otherwise depend
8634	on their address (or the address or their subobjects) should not be declared
8635	``[[trivial_abi]]``.
8636
8637	Attribute ``trivial_abi`` has no effect in the following cases:
8638
8639	- The class directly declares a virtual base or virtual methods.
8640	- Copy constructors and move constructors of the class are all deleted.
8641	- The class has a base class that is non-trivial for the purposes of calls.
8642	- The class has a non-static data member whose type is non-trivial for the
8643	purposes of calls, which includes:
8644
8645	- classes that are non-trivial for the purposes of calls
8646	- __weak-qualified types in Objective-C++
8647	- arrays of any of the above)reST";
8648
8649	static const char AttrDoc_TryAcquireCapability[] = R"reST(Marks a function that attempts to acquire a capability. This function may fail to
8650	actually acquire the capability; they accept a Boolean value determining
8651	whether acquiring the capability means success (true), or failing to acquire
8652	the capability means success (false).)reST";
8653
8654	static const char AttrDoc_TypeNonNull[] = R"reST(The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful
8655	value for a value of the ``_Nonnull`` pointer type. For example, given a
8656	declaration such as:
8657
8658	.. code-block:: c
8659
8660	int fetch(int * _Nonnull ptr);
8661
8662	a caller of ``fetch`` should not provide a null value, and the compiler will
8663	produce a warning if it sees a literal null value passed to ``fetch``. Note
8664	that, unlike the declaration attribute ``nonnull``, the presence of
8665	``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch``
8666	is free to consider null undefined behavior or (perhaps for
8667	backward-compatibility reasons) defensively handle null.)reST";
8668
8669	static const char AttrDoc_TypeNullUnspecified[] = R"reST(The ``_Null_unspecified`` nullability qualifier indicates that neither the
8670	``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer
8671	type. It is used primarily to indicate that the role of null with specific
8672	pointers in a nullability-annotated header is unclear, e.g., due to
8673	overly-complex implementations or historical factors with a long-lived API.)reST";
8674
8675	static const char AttrDoc_TypeNullable[] = R"reST(The ``_Nullable`` nullability qualifier indicates that a value of the
8676	``_Nullable`` pointer type can be null. For example, given:
8677
8678	.. code-block:: c
8679
8680	int fetch_or_zero(int * _Nullable ptr);
8681
8682	a caller of ``fetch_or_zero`` can provide null.
8683
8684	The ``_Nullable`` attribute on classes indicates that the given class can
8685	represent null values, and so the ``_Nullable``, ``_Nonnull`` etc qualifiers
8686	make sense for this type. For example:
8687
8688	.. code-block:: c
8689
8690	class _Nullable ArenaPointer { ... };
8691
8692	ArenaPointer _Nonnull x = ...;
8693	ArenaPointer _Nullable y = nullptr;)reST";
8694
8695	static const char AttrDoc_TypeNullableResult[] = R"reST(The ``_Nullable_result`` nullability qualifier means that a value of the
8696	``_Nullable_result`` pointer can be ``nil``, just like ``_Nullable``. Where this
8697	attribute differs from ``_Nullable`` is when it's used on a parameter to a
8698	completion handler in a Swift async method. For instance, here:
8699
8700	.. code-block:: objc
8701
8702	-(void)fetchSomeDataWithID:(int)identifier
8703	completionHandler:(void (^)(Data _Nullable_result result, NSError error))completionHandler;
8704
8705	This method asynchronously calls ``completionHandler`` when the data is
8706	available, or calls it with an error. ``_Nullable_result`` indicates to the
8707	Swift importer that this is the uncommon case where ``result`` can get ``nil``
8708	even if no error has occurred, and will therefore import it as a Swift optional
8709	type. Otherwise, if ``result`` was annotated with ``_Nullable``, the Swift
8710	importer will assume that ``result`` will always be non-nil unless an error
8711	occurred.)reST";
8712
8713	static const char AttrDoc_TypeTagForDatatype[] = R"reST(When declaring a variable, use
8714	``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
8715	is tied to the ``type`` argument given to the attribute.
8716
8717	In the attribute prototype above:
8718	* ``kind`` is an identifier that should be used when annotating all applicable
8719	type tags.
8720	* ``type`` indicates the name of the type.
8721
8722	Clang supports annotating type tags of two forms.
8723
8724	* Type tag that is a reference to a declared identifier.
8725	Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
8726	identifier:
8727
8728	.. code-block:: c++
8729
8730	typedef int MPI_Datatype;
8731	extern struct mpi_datatype mpi_datatype_int
8732	__attribute__(( type_tag_for_datatype(mpi,int) ));
8733	#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
8734	// &mpi_datatype_int is a type tag. It is tied to type "int".
8735
8736	* Type tag that is an integral literal.
8737	Declare a ``static const`` variable with an initializer value and attach
8738	``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
8739
8740	.. code-block:: c++
8741
8742	typedef int MPI_Datatype;
8743	static const MPI_Datatype mpi_datatype_int
8744	__attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
8745	#define MPI_INT ((MPI_Datatype) 42)
8746	// The number 42 is a type tag. It is tied to type "int".
8747
8748
8749	The ``type_tag_for_datatype`` attribute also accepts an optional third argument
8750	that determines how the type of the function argument specified by either
8751	``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
8752	tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
8753	function argument specified by ``arg_idx`` is compared against the type
8754	associated with the type tag. Also recall that for the ``pointer_with_type_tag``
8755	attribute, the pointee type of the function argument specified by ``ptr_idx`` is
8756	compared against the type associated with the type tag.) There are two supported
8757	values for this optional third argument:
8758
8759	* ``layout_compatible`` will cause types to be compared according to
8760	layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
8761	layout-compatibility rules for two standard-layout struct types and for two
8762	standard-layout union types). This is useful when creating a type tag
8763	associated with a struct or union type. For example:
8764
8765	.. code-block:: c++
8766
8767	/* In mpi.h */
8768	typedef int MPI_Datatype;
8769	struct internal_mpi_double_int { double d; int i; };
8770	extern struct mpi_datatype mpi_datatype_double_int
8771	__attribute__(( type_tag_for_datatype(mpi,
8772	struct internal_mpi_double_int, layout_compatible) ));
8773
8774	#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
8775
8776	int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
8777	__attribute__(( pointer_with_type_tag(mpi,1,3) ));
8778
8779	/* In user code */
8780	struct my_pair { double a; int b; };
8781	struct my_pair *buffer;
8782	MPI_Send(buffer, 1, MPI_DOUBLE_INT /, ... /); // no warning because the
8783	// layout of my_pair is
8784	// compatible with that of
8785	// internal_mpi_double_int
8786
8787	struct my_int_pair { int a; int b; }
8788	struct my_int_pair *buffer2;
8789	MPI_Send(buffer2, 1, MPI_DOUBLE_INT /, ... /); // warning because the
8790	// layout of my_int_pair
8791	// does not match that of
8792	// internal_mpi_double_int
8793
8794	* ``must_be_null`` specifies that the function argument specified by either
8795	``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
8796	the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
8797	The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
8798	example:
8799
8800	.. code-block:: c++
8801
8802	/* In mpi.h */
8803	typedef int MPI_Datatype;
8804	extern struct mpi_datatype mpi_datatype_null
8805	__attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
8806
8807	#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
8808	int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
8809	__attribute__(( pointer_with_type_tag(mpi,1,3) ));
8810
8811	/* In user code */
8812	struct my_pair { double a; int b; };
8813	struct my_pair *buffer;
8814	MPI_Send(buffer, 1, MPI_DATATYPE_NULL /, ... /); // warning: MPI_DATATYPE_NULL
8815	// was specified but buffer
8816	// is not a null pointer)reST";
8817
8818	static const char AttrDoc_TypeVisibility[] = R"reST(The ``type_visibility`` attribute allows the visibility of a type and its vague
8819	linkage objects (vtable, typeinfo, typeinfo name) to be controlled separately from
8820	the visibility of functions and data members of the type.
8821
8822	For example, this can be used to give default visibility to the typeinfo and the vtable
8823	of a type while still keeping hidden visibility on its member functions and static data
8824	members.
8825
8826	This attribute can only be applied to types and namespaces.
8827
8828	If both ``visibility`` and ``type_visibility`` are applied to a type or a namespace, the
8829	visibility specified with the ``type_visibility`` attribute overrides the visibility
8830	provided with the regular ``visibility`` attribute.)reST";
8831
8832	static const char AttrDoc_UPtr[] = R"reST(The ``__uptr`` qualifier specifies that a 32-bit pointer should be zero
8833	extended when converted to a 64-bit pointer.)reST";
8834
8835	static const char AttrDoc_Unavailable[] = R"reST(No documentation.)reST";
8836
8837	static const char AttrDoc_Uninitialized[] = R"reST(The command-line parameter ``-ftrivial-auto-var-init=*`` can be used to
8838	initialize trivial automatic stack variables. By default, trivial automatic
8839	stack variables are uninitialized. This attribute is used to override the
8840	command-line parameter, forcing variables to remain uninitialized. It has no
8841	semantic meaning in that using uninitialized values is undefined behavior,
8842	it rather documents the programmer's intent.)reST";
8843
8844	static const char AttrDoc_Unlikely[] = R"reST(The ``likely`` and ``unlikely`` attributes are used as compiler hints.
8845	The attributes are used to aid the compiler to determine which branch is
8846	likely or unlikely to be taken. This is done by marking the branch substatement
8847	with one of the two attributes.
8848
8849	It isn't allowed to annotate a single statement with both ``likely`` and
8850	``unlikely``. Annotating the ``true`` and ``false`` branch of an ``if``
8851	statement with the same likelihood attribute will result in a diagnostic and
8852	the attributes are ignored on both branches.
8853
8854	In a ``switch`` statement it's allowed to annotate multiple ``case`` labels
8855	or the ``default`` label with the same likelihood attribute. This makes
8856	* all labels without an attribute have a neutral likelihood,
8857	* all labels marked ``[[likely]]`` have an equally positive likelihood, and
8858	* all labels marked ``[[unlikely]]`` have an equally negative likelihood.
8859	The neutral likelihood is the more likely of path execution than the negative
8860	likelihood. The positive likelihood is the more likely of path of execution
8861	than the neutral likelihood.
8862
8863	These attributes have no effect on the generated code when using
8864	PGO (Profile-Guided Optimization) or at optimization level 0.
8865
8866	In Clang, the attributes will be ignored if they're not placed on
8867	* the ``case`` or ``default`` label of a ``switch`` statement,
8868	* or on the substatement of an ``if`` or ``else`` statement,
8869	* or on the substatement of an ``for`` or ``while`` statement.
8870	The C++ Standard recommends to honor them on every statement in the
8871	path of execution, but that can be confusing:
8872
8873	.. code-block:: c++
8874
8875	if (b) {
8876	[[unlikely]] --b; // Per the standard this is in the path of
8877	// execution, so this branch should be considered
8878	// unlikely. However, Clang ignores the attribute
8879	// here since it is not on the substatement.
8880	}
8881
8882	if (b) {
8883	--b;
8884	if(b)
8885	return;
8886	[[unlikely]] --b; // Not in the path of execution,
8887	} // the branch has no likelihood information.
8888
8889	if (b) {
8890	--b;
8891	foo(b);
8892	// Whether or not the next statement is in the path of execution depends
8893	// on the declaration of foo():
8894	// In the path of execution: void foo(int);
8895	// Not in the path of execution: [[noreturn]] void foo(int);
8896	// This means the likelihood of the branch depends on the declaration
8897	// of foo().
8898	[[unlikely]] --b;
8899	}
8900
8901
8902	Below are some example usages of the likelihood attributes and their effects:
8903
8904	.. code-block:: c++
8905
8906	if (b) [[likely]] { // Placement on the first statement in the branch.
8907	// The compiler will optimize to execute the code here.
8908	} else {
8909	}
8910
8911	if (b)
8912	[[unlikely]] b++; // Placement on the first statement in the branch.
8913	else {
8914	// The compiler will optimize to execute the code here.
8915	}
8916
8917	if (b) {
8918	[[unlikely]] b++; // Placement on the second statement in the branch.
8919	} // The attribute will be ignored.
8920
8921	if (b) [[likely]] {
8922	[[unlikely]] b++; // No contradiction since the second attribute
8923	} // is ignored.
8924
8925	if (b)
8926	;
8927	else [[likely]] {
8928	// The compiler will optimize to execute the code here.
8929	}
8930
8931	if (b)
8932	;
8933	else
8934	// The compiler will optimize to execute the next statement.
8935	[[likely]] b = f();
8936
8937	if (b) [[likely]]; // Both branches are likely. A diagnostic is issued
8938	else [[likely]]; // and the attributes are ignored.
8939
8940	if (b)
8941	[[likely]] int i = 5; // Issues a diagnostic since the attribute
8942	// isn't allowed on a declaration.
8943
8944	switch (i) {
8945	[[likely]] case 1: // This value is likely
8946	...
8947	break;
8948
8949	[[unlikely]] case 2: // This value is unlikely
8950	...
8951	[[fallthrough]];
8952
8953	case 3: // No likelihood attribute
8954	...
8955	[[likely]] break; // No effect
8956
8957	case 4: [[likely]] { // attribute on substatement has no effect
8958	...
8959	break;
8960	}
8961
8962	[[unlikely]] default: // All other values are unlikely
8963	...
8964	break;
8965	}
8966
8967	switch (i) {
8968	[[likely]] case 0: // This value and code path is likely
8969	...
8970	[[fallthrough]];
8971
8972	case 1: // No likelihood attribute, code path is neutral
8973	break; // falling through has no effect on the likelihood
8974
8975	case 2: // No likelihood attribute, code path is neutral
8976	[[fallthrough]];
8977
8978	[[unlikely]] default: // This value and code path are both unlikely
8979	break;
8980	}
8981
8982	for(int i = 0; i != size; ++i) [[likely]] {
8983	... // The loop is the likely path of execution
8984	}
8985
8986	for(const auto &E : Elements) [[likely]] {
8987	... // The loop is the likely path of execution
8988	}
8989
8990	while(i != size) [[unlikely]] {
8991	... // The loop is the unlikely path of execution
8992	} // The generated code will optimize to skip the loop body
8993
8994	while(true) [[unlikely]] {
8995	... // The attribute has no effect
8996	} // Clang elides the comparison and generates an infinite
8997	// loop)reST";
8998
8999	static const char AttrDoc_UnsafeBufferUsage[] = R"reST(The attribute ``[[clang::unsafe_buffer_usage]]`` should be placed on functions
9000	that need to be avoided as they are prone to buffer overflows or unsafe buffer
9001	struct fields. It is designed to work together with the off-by-default compiler
9002	warning ``-Wunsafe-buffer-usage`` to help codebases transition away from raw pointer
9003	based buffer management, in favor of safer abstractions such as C++20 ``std::span``.
9004	The attribute causes ``-Wunsafe-buffer-usage`` to warn on every use of the function or
9005	the field it is attached to, and it may also lead to emission of automatic fix-it
9006	hints which would help the user replace the use of unsafe functions(/fields) with safe
9007	alternatives, though the attribute can be used even when the fix can't be automated.
9008
9009	* Attribute attached to functions: The attribute suppresses all
9010	``-Wunsafe-buffer-usage`` warnings within the function it is attached to, as the
9011	function is now classified as unsafe. The attribute should be used carefully, as it
9012	will silence all unsafe operation warnings inside the function; including any new
9013	unsafe operations introduced in the future.
9014
9015	The attribute is warranted even if the only way a function can overflow
9016	the buffer is by violating the function's preconditions. For example, it
9017	would make sense to put the attribute on function ``foo()`` below because
9018	passing an incorrect size parameter would cause a buffer overflow:
9019
9020	.. code-block:: c++
9021
9022	[[clang::unsafe_buffer_usage]]
9023	void foo(int *buf, size_t size) {
9024	for (size_t i = 0; i < size; ++i) {
9025	buf[i] = i;
9026	}
9027	}
9028
9029	The attribute is NOT warranted when the function uses safe abstractions,
9030	assuming that these abstractions weren't misused outside the function.
9031	For example, function ``bar()`` below doesn't need the attribute,
9032	because assuming that the container ``buf`` is well-formed (has size that
9033	fits the original buffer it refers to), overflow cannot occur:
9034
9035	.. code-block:: c++
9036
9037	void bar(std::span<int> buf) {
9038	for (size_t i = 0; i < buf.size(); ++i) {
9039	buf[i] = i;
9040	}
9041	}
9042
9043	In this case function ``bar()`` enables the user to keep the buffer
9044	"containerized" in a span for as long as possible. On the other hand,
9045	Function ``foo()`` in the previous example may have internal
9046	consistency, but by accepting a raw buffer it requires the user to unwrap
9047	their span, which is undesirable according to the programming model
9048	behind ``-Wunsafe-buffer-usage``.
9049
9050	The attribute is warranted when a function accepts a raw buffer only to
9051	immediately put it into a span:
9052
9053	.. code-block:: c++
9054
9055	[[clang::unsafe_buffer_usage]]
9056	void baz(int *buf, size_t size) {
9057	std::span<int> sp{ buf, size };
9058	for (size_t i = 0; i < sp.size(); ++i) {
9059	sp[i] = i;
9060	}
9061	}
9062
9063	In this case ``baz()`` does not contain any unsafe operations, but the awkward
9064	parameter type causes the caller to unwrap the span unnecessarily.
9065	Note that regardless of the attribute, code inside ``baz()`` isn't flagged
9066	by ``-Wunsafe-buffer-usage`` as unsafe. It is definitely undesirable,
9067	but if ``baz()`` is on an API surface, there is no way to improve it
9068	to make it as safe as ``bar()`` without breaking the source and binary
9069	compatibility with existing users of the function. In such cases
9070	the proper solution would be to create a different function (possibly
9071	an overload of ``baz()``) that accepts a safe container like ``bar()``,
9072	and then use the attribute on the original ``baz()`` to help the users
9073	update their code to use the new function.
9074
9075	* Attribute attached to fields: The attribute should only be attached to
9076	struct fields, if the fields can not be updated to a safe type with bounds
9077	check, such as std::span. In other words, the buffers prone to unsafe accesses
9078	should always be updated to use safe containers/views and attaching the attribute
9079	must be last resort when such an update is infeasible.
9080
9081	The attribute can be placed on individual fields or a set of them as shown below.
9082
9083	.. code-block:: c++
9084
9085	struct A {
9086	[[clang::unsafe_buffer_usage]]
9087	int *ptr1;
9088
9089	[[clang::unsafe_buffer_usage]]
9090	int *ptr2, buf[10];
9091
9092	[[clang::unsafe_buffer_usage]]
9093	size_t sz;
9094	};
9095
9096	Here, every read/write to the fields ptr1, ptr2, buf and sz will trigger a warning
9097	that the field has been explcitly marked as unsafe due to unsafe-buffer operations.)reST";
9098
9099	static const char AttrDoc_Unused[] = R"reST(When passing the ``-Wunused`` flag to Clang, entities that are unused by the
9100	program may be diagnosed. The ``[[maybe_unused]]`` (or
9101	``__attribute__((unused))``) attribute can be used to silence such diagnostics
9102	when the entity cannot be removed. For instance, a local variable may exist
9103	solely for use in an ``assert()`` statement, which makes the local variable
9104	unused when ``NDEBUG`` is defined.
9105
9106	The attribute may be applied to the declaration of a class, a typedef, a
9107	variable, a function or method, a function parameter, an enumeration, an
9108	enumerator, a non-static data member, or a label.
9109
9110	.. code-block:: c++
9111
9112	#include <cassert>
9113
9114	[[maybe_unused]] void f([[maybe_unused]] bool thing1,
9115	[[maybe_unused]] bool thing2) {
9116	[[maybe_unused]] bool b = thing1 && thing2;
9117	assert(b);
9118	})reST";
9119
9120	static const char AttrDoc_UseHandle[] = R"reST(A function taking a handle by value might close the handle. If a function
9121	parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
9122	the state of the handle. It is also assumed to require an open handle to work with.
9123	The attribute requires a string literal argument to identify the handle being used.
9124
9125	.. code-block:: c++
9126
9127	zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
9128	zx_time_t deadline,
9129	zx_port_packet_t* packet);)reST";
9130
9131	static const char AttrDoc_Used[] = R"reST(This attribute, when attached to a function or variable definition, indicates
9132	that there may be references to the entity which are not apparent in the source
9133	code. For example, it may be referenced from inline ``asm``, or it may be
9134	found through a dynamic symbol or section lookup.
9135
9136	The compiler must emit the definition even if it appears to be unused, and it
9137	must not apply optimizations which depend on fully understanding how the entity
9138	is used.
9139
9140	Whether this attribute has any effect on the linker depends on the target and
9141	the linker. Most linkers support the feature of section garbage collection
9142	(``--gc-sections``), also known as "dead stripping" (``ld64 -dead_strip``) or
9143	discarding unreferenced sections (``link.exe /OPT:REF``). On COFF and Mach-O
9144	targets (Windows and Apple platforms), the `used` attribute prevents symbols
9145	from being removed by linker section GC. On ELF targets, it has no effect on its
9146	own, and the linker may remove the definition if it is not otherwise referenced.
9147	This linker GC can be avoided by also adding the ``retain`` attribute. Note
9148	that ``retain`` requires special support from the linker; see that attribute's
9149	documentation for further information.)reST";
9150
9151	static const char AttrDoc_UsingIfExists[] = R"reST(The ``using_if_exists`` attribute applies to a using-declaration. It allows
9152	programmers to import a declaration that potentially does not exist, instead
9153	deferring any errors to the point of use. For instance:
9154
9155	.. code-block:: c++
9156
9157	namespace empty_namespace {};
9158	__attribute__((using_if_exists))
9159	using empty_namespace::does_not_exist; // no error!
9160
9161	does_not_exist x; // error: use of unresolved 'using_if_exists'
9162
9163	The C++ spelling of the attribute (`[[clang::using_if_exists]]`) is also
9164	supported as a clang extension, since ISO C++ doesn't support attributes in this
9165	position. If the entity referred to by the using-declaration is found by name
9166	lookup, the attribute has no effect. This attribute is useful for libraries
9167	(primarily, libc++) that wish to redeclare a set of declarations in another
9168	namespace, when the availability of those declarations is difficult or
9169	impossible to detect at compile time with the preprocessor.)reST";
9170
9171	static const char AttrDoc_Uuid[] = R"reST(No documentation.)reST";
9172
9173	static const char AttrDoc_VTablePointerAuthentication[] = R"reST(No documentation.)reST";
9174
9175	static const char AttrDoc_VecReturn[] = R"reST(No documentation.)reST";
9176
9177	static const char AttrDoc_VecTypeHint[] = R"reST(No documentation.)reST";
9178
9179	static const char AttrDoc_VectorCall[] = R"reST(On 32-bit x86 and x86_64 targets, this attribute changes the calling
9180	convention of a function to pass vector parameters in SSE registers.
9181
9182	On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
9183	The first two integer parameters are passed in ECX and EDX. Subsequent integer
9184	parameters are passed in memory, and callee clears the stack. On x86_64
9185	targets, the callee does not clear the stack, and integer parameters are
9186	passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
9187	convention.
9188
9189	On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
9190	passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
9191	passed in sequential SSE registers if enough are available. If AVX is enabled,
9192	256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
9193	cannot be passed in registers for any reason is passed by reference, which
9194	allows the caller to align the parameter memory.
9195
9196	See the documentation for `__vectorcall`_ on MSDN for more details.
9197
9198	.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx)reST";
9199
9200	static const char AttrDoc_Visibility[] = R"reST(No documentation.)reST";
9201
9202	static const char AttrDoc_WarnUnused[] = R"reST(No documentation.)reST";
9203
9204	static const char AttrDoc_WarnUnusedResult[] = R"reST(Clang supports the ability to diagnose when the results of a function call
9205	expression are discarded under suspicious circumstances. A diagnostic is
9206	generated when a function or its return type is marked with ``[[nodiscard]]``
9207	(or ``__attribute__((warn_unused_result))``) and the function call appears as a
9208	potentially-evaluated discarded-value expression that is not explicitly cast to
9209	``void``.
9210
9211	A string literal may optionally be provided to the attribute, which will be
9212	reproduced in any resulting diagnostics. Redeclarations using different forms
9213	of the attribute (with or without the string literal or with different string
9214	literal contents) are allowed. If there are redeclarations of the entity with
9215	differing string literals, it is unspecified which one will be used by Clang
9216	in any resulting diagnostics.
9217
9218	.. code-block:: c++
9219
9220	struct [[nodiscard]] error_info { /.../ };
9221	error_info enable_missile_safety_mode();
9222
9223	void launch_missiles();
9224	void test_missiles() {
9225	enable_missile_safety_mode(); // diagnoses
9226	launch_missiles();
9227	}
9228	error_info &foo();
9229	void f() { foo(); } // Does not diagnose, error_info is a reference.
9230
9231	Additionally, discarded temporaries resulting from a call to a constructor
9232	marked with ``[[nodiscard]]`` or a constructor of a type marked
9233	``[[nodiscard]]`` will also diagnose. This also applies to type conversions that
9234	use the annotated ``[[nodiscard]]`` constructor or result in an annotated type.
9235
9236	.. code-block:: c++
9237
9238	struct [[nodiscard]] marked_type {/../ };
9239	struct marked_ctor {
9240	[[nodiscard]] marked_ctor();
9241	marked_ctor(int);
9242	};
9243
9244	struct S {
9245	operator marked_type() const;
9246	[[nodiscard]] operator int() const;
9247	};
9248
9249	void usages() {
9250	marked_type(); // diagnoses.
9251	marked_ctor(); // diagnoses.
9252	marked_ctor(3); // Does not diagnose, int constructor isn't marked nodiscard.
9253
9254	S s;
9255	static_cast<marked_type>(s); // diagnoses
9256	(int)s; // diagnoses
9257	})reST";
9258
9259	static const char AttrDoc_Weak[] = R"reST(In supported output formats the ``weak`` attribute can be used to
9260	specify that a variable or function should be emitted as a symbol with
9261	``weak`` (if a definition) or ``extern_weak`` (if a declaration of an
9262	external symbol) `linkage
9263	<https://llvm.org/docs/LangRef.html#linkage-types>`_.
9264
9265	If there is a non-weak definition of the symbol the linker will select
9266	that over the weak. They must have same type and alignment (variables
9267	must also have the same size), but may have a different value.
9268
9269	If there are multiple weak definitions of same symbol, but no non-weak
9270	definition, they should have same type, size, alignment and value, the
9271	linker will select one of them (see also selectany_ attribute).
9272
9273	If the ``weak`` attribute is applied to a ``const`` qualified variable
9274	definition that variable is no longer consider a compiletime constant
9275	as its value can change during linking (or dynamic linking). This
9276	means that it can e.g no longer be part of an initializer expression.
9277
9278	.. code-block:: c
9279
9280	const int ANSWER __attribute__ ((weak)) = 42;
9281
9282	/* This function may be replaced link-time */
9283	__attribute__ ((weak)) void debug_log(const char *msg)
9284	{
9285	fprintf(stderr, "DEBUG: %s\n", msg);
9286	}
9287
9288	int main(int argc, const char **argv)
9289	{
9290	debug_log ("Starting up...");
9291
9292	/* This may print something else than "6 * 7 = 42",
9293	if there is a non-weak definition of "ANSWER" in
9294	an object linked in */
9295	printf("6 * 7 = %d\n", ANSWER);
9296
9297	return 0;
9298	}
9299
9300	If an external declaration is marked weak and that symbol does not
9301	exist during linking (possibly dynamic) the address of the symbol will
9302	evaluate to NULL.
9303
9304	.. code-block:: c
9305
9306	void may_not_exist(void) __attribute__ ((weak));
9307
9308	int main(int argc, const char **argv)
9309	{
9310	if (may_not_exist) {
9311	may_not_exist();
9312	} else {
9313	printf("Function did not exist\n");
9314	}
9315	return 0;
9316	})reST";
9317
9318	static const char AttrDoc_WeakImport[] = R"reST(No documentation.)reST";
9319
9320	static const char AttrDoc_WeakRef[] = R"reST(No documentation.)reST";
9321
9322	static const char AttrDoc_WebAssemblyExportName[] = R"reST(Clang supports the ``__attribute__((export_name(<name>)))``
9323	attribute for the WebAssembly target. This attribute may be attached to a
9324	function declaration, where it modifies how the symbol is to be exported
9325	from the linked WebAssembly.
9326
9327	WebAssembly functions are exported via string name. By default when a symbol
9328	is exported, the export name for C/C++ symbols are the same as their C/C++
9329	symbol names. This attribute can be used to override the default behavior, and
9330	request a specific string name be used instead.)reST";
9331
9332	static const char AttrDoc_WebAssemblyFuncref[] = R"reST(Clang supports the ``__attribute__((export_name(<name>)))``
9333	attribute for the WebAssembly target. This attribute may be attached to a
9334	function declaration, where it modifies how the symbol is to be exported
9335	from the linked WebAssembly.
9336
9337	WebAssembly functions are exported via string name. By default when a symbol
9338	is exported, the export name for C/C++ symbols are the same as their C/C++
9339	symbol names. This attribute can be used to override the default behavior, and
9340	request a specific string name be used instead.)reST";
9341
9342	static const char AttrDoc_WebAssemblyImportModule[] = R"reST(Clang supports the ``__attribute__((import_module(<module_name>)))``
9343	attribute for the WebAssembly target. This attribute may be attached to a
9344	function declaration, where it modifies how the symbol is to be imported
9345	within the WebAssembly linking environment.
9346
9347	WebAssembly imports use a two-level namespace scheme, consisting of a module
9348	name, which typically identifies a module from which to import, and a field
9349	name, which typically identifies a field from that module to import. By
9350	default, module names for C/C++ symbols are assigned automatically by the
9351	linker. This attribute can be used to override the default behavior, and
9352	request a specific module name be used instead.)reST";
9353
9354	static const char AttrDoc_WebAssemblyImportName[] = R"reST(Clang supports the ``__attribute__((import_name(<name>)))``
9355	attribute for the WebAssembly target. This attribute may be attached to a
9356	function declaration, where it modifies how the symbol is to be imported
9357	within the WebAssembly linking environment.
9358
9359	WebAssembly imports use a two-level namespace scheme, consisting of a module
9360	name, which typically identifies a module from which to import, and a field
9361	name, which typically identifies a field from that module to import. By
9362	default, field names for C/C++ symbols are the same as their C/C++ symbol
9363	names. This attribute can be used to override the default behavior, and
9364	request a specific field name be used instead.)reST";
9365
9366	static const char AttrDoc_WorkGroupSizeHint[] = R"reST(No documentation.)reST";
9367
9368	static const char AttrDoc_X86ForceAlignArgPointer[] = R"reST(Use this attribute to force stack alignment.
9369
9370	Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
9371	(like 'movaps') that work with the stack require operands to be 16-byte aligned.
9372	This attribute realigns the stack in the function prologue to make sure the
9373	stack can be used with SSE instructions.
9374
9375	Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
9376	Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
9377	rare cases where the caller does not align the stack properly (e.g. flow
9378	jumps from i386 arch code).
9379
9380	.. code-block:: c
9381
9382	__attribute__ ((force_align_arg_pointer))
9383	void f () {
9384	...
9385	})reST";
9386
9387	static const char AttrDoc_XRayInstrument[] = R"reST(``__attribute__((xray_always_instrument))`` or
9388	``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++),
9389	methods (in Objective C), and free functions (in C, C++, and Objective C) to be
9390	instrumented with XRay. This will cause the function to always have space at
9391	the beginning and exit points to allow for runtime patching.
9392
9393	Conversely, ``__attribute__((xray_never_instrument))`` or
9394	``[[clang::xray_never_instrument]]`` will inhibit the insertion of these
9395	instrumentation points.
9396
9397	If a function has neither of these attributes, they become subject to the XRay
9398	heuristics used to determine whether a function should be instrumented or
9399	otherwise.
9400
9401	``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is
9402	used to preserve N function arguments for the logging function. Currently,
9403	only N==1 is supported.)reST";
9404
9405	static const char AttrDoc_XRayLogArgs[] = R"reST(``__attribute__((xray_always_instrument))`` or
9406	``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++),
9407	methods (in Objective C), and free functions (in C, C++, and Objective C) to be
9408	instrumented with XRay. This will cause the function to always have space at
9409	the beginning and exit points to allow for runtime patching.
9410
9411	Conversely, ``__attribute__((xray_never_instrument))`` or
9412	``[[clang::xray_never_instrument]]`` will inhibit the insertion of these
9413	instrumentation points.
9414
9415	If a function has neither of these attributes, they become subject to the XRay
9416	heuristics used to determine whether a function should be instrumented or
9417	otherwise.
9418
9419	``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is
9420	used to preserve N function arguments for the logging function. Currently,
9421	only N==1 is supported.)reST";
9422
9423	static const char AttrDoc_ZeroCallUsedRegs[] = R"reST(This attribute, when attached to a function, causes the compiler to zero a
9424	subset of all call-used registers before the function returns. It's used to
9425	increase program security by either mitigating `Return-Oriented Programming`_
9426	(ROP) attacks or preventing information leakage through registers.
9427
9428	The term "call-used" means registers which are not guaranteed to be preserved
9429	unchanged for the caller by the current calling convention. This could also be
9430	described as "caller-saved" or "not callee-saved".
9431
9432	The `choice` parameters gives the programmer flexibility to choose the subset
9433	of the call-used registers to be zeroed:
9434
9435	- ``skip`` doesn't zero any call-used registers. This choice overrides any
9436	command-line arguments.
9437	- ``used`` only zeros call-used registers used in the function. By ``used``, we
9438	mean a register whose contents have been set or referenced in the function.
9439	- ``used-gpr`` only zeros call-used GPR registers used in the function.
9440	- ``used-arg`` only zeros call-used registers used to pass arguments to the
9441	function.
9442	- ``used-gpr-arg`` only zeros call-used GPR registers used to pass arguments to
9443	the function.
9444	- ``all`` zeros all call-used registers.
9445	- ``all-gpr`` zeros all call-used GPR registers.
9446	- ``all-arg`` zeros all call-used registers used to pass arguments to the
9447	function.
9448	- ``all-gpr-arg`` zeros all call-used GPR registers used to pass arguments to
9449	the function.
9450
9451	The default for the attribute is controlled by the ``-fzero-call-used-regs``
9452	flag.
9453
9454	.. _Return-Oriented Programming: https://en.wikipedia.org/wiki/Return-oriented_programming)reST";
9455

Browse the source code of llvm_projects/build/tools/clang/lib/AST/AttrDocTable.inc