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(No documentation.)reST";
284
285	static const char AttrDoc_Alias[] = R"reST(No documentation.)reST";
286
287	static const char AttrDoc_AlignMac68k[] = R"reST()reST";
288
289	static const char AttrDoc_AlignNatural[] = R"reST()reST";
290
291	static const char AttrDoc_AlignValue[] = R"reST(The align_value attribute can be added to the typedef of a pointer type or the
292	declaration of a variable of pointer or reference type. It specifies that the
293	pointer will point to, or the reference will bind to, only objects with at
294	least the provided alignment. This alignment value must be some positive power
295	of 2.
296
297	.. code-block:: c
298
299	typedef double * aligned_double_ptr __attribute__((align_value(64)));
300	void foo(double & x __attribute__((align_value(128))),
301	aligned_double_ptr y) { ... }
302
303	If the pointer value does not have the specified alignment at runtime, the
304	behavior of the program is undefined.)reST";
305
306	static const char AttrDoc_Aligned[] = R"reST(No documentation.)reST";
307
308	static const char AttrDoc_AllocAlign[] = R"reST(Use ``__attribute__((alloc_align(<alignment>))`` on a function
309	declaration to specify that the return value of the function (which must be a
310	pointer type) is at least as aligned as the value of the indicated parameter. The
311	parameter is given by its index in the list of formal parameters; the first
312	parameter has index 1 unless the function is a C++ non-static member function,
313	in which case the first parameter has index 2 to account for the implicit ``this``
314	parameter.
315
316	.. code-block:: c++
317
318	// The returned pointer has the alignment specified by the first parameter.
319	void *a(size_t align) __attribute__((alloc_align(1)));
320
321	// The returned pointer has the alignment specified by the second parameter.
322	void b(void v, size_t align) __attribute__((alloc_align(2)));
323
324	// The returned pointer has the alignment specified by the second visible
325	// parameter, however it must be adjusted for the implicit 'this' parameter.
326	void Foo::b(void v, size_t align) __attribute__((alloc_align(3)));
327
328	Note that this attribute merely informs the compiler that a function always
329	returns a sufficiently aligned pointer. It does not cause the compiler to
330	emit code to enforce that alignment. The behavior is undefined if the returned
331	pointer is not sufficiently aligned.)reST";
332
333	static const char AttrDoc_AllocSize[] = R"reST(The ``alloc_size`` attribute can be placed on functions that return pointers in
334	order to hint to the compiler how many bytes of memory will be available at the
335	returned pointer. ``alloc_size`` takes one or two arguments.
336
337	- ``alloc_size(N)`` implies that argument number N equals the number of
338	available bytes at the returned pointer.
339	- ``alloc_size(N, M)`` implies that the product of argument number N and
340	argument number M equals the number of available bytes at the returned
341	pointer.
342
343	Argument numbers are 1-based.
344
345	An example of how to use ``alloc_size``
346
347	.. code-block:: c
348
349	void *my_malloc(int a) __attribute__((alloc_size(1)));
350	void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
351
352	int main() {
353	void *const p = my_malloc(100);
354	assert(__builtin_object_size(p, 0) == 100);
355	void *const a = my_calloc(20, 5);
356	assert(__builtin_object_size(a, 0) == 100);
357	}
358
359	When ``-Walloc-size`` is enabled, this attribute allows the compiler to
360	diagnose cases when the allocated memory is insufficient for the size of the
361	type the returned pointer is cast to.
362
363	.. code-block:: c
364
365	void *my_malloc(int a) __attribute__((alloc_size(1)));
366	void consumer_func(int *);
367
368	int main() {
369	int *ptr = my_malloc(sizeof(int)); // no warning
370	int *w = my_malloc(1); // warning: allocation of insufficient size '1' for type 'int' with size '4'
371	consumer_func(my_malloc(1)); // warning: allocation of insufficient size '1' for type 'int' with size '4'
372	}
373
374	.. Note:: This attribute works differently in clang than it does in GCC.
375	Specifically, clang will only trace ``const`` pointers (as above); we give up
376	on pointers that are not marked as ``const``. In the vast majority of cases,
377	this is unimportant, because LLVM has support for the ``alloc_size``
378	attribute. However, this may cause mildly unintuitive behavior when used with
379	other attributes, such as ``enable_if``.)reST";
380
381	static const char AttrDoc_Allocating[] = R"reST(Declares that a function potentially allocates heap memory, and prevents any potential inference
382	of ``nonallocating`` by the compiler.)reST";
383
384	static const char AttrDoc_AlwaysDestroy[] = R"reST(The ``always_destroy`` attribute specifies that a variable with static or thread
385	storage duration should have its exit-time destructor run. This attribute is the
386	default unless clang was invoked with -fno-c++-static-destructors.
387
388	If a variable is explicitly declared with this attribute, Clang will silence
389	otherwise applicable ``-Wexit-time-destructors`` warnings.)reST";
390
391	static const char AttrDoc_AlwaysInline[] = R"reST(Inlining heuristics are disabled and inlining is always attempted regardless of
392	optimization level.
393
394	``[[clang::always_inline]]`` spelling can be used as a statement attribute; other
395	spellings of the attribute are not supported on statements. If a statement is
396	marked ``[[clang::always_inline]]`` and contains calls, the compiler attempts
397	to inline those calls.
398
399	.. code-block:: c
400
401	int example(void) {
402	int i;
403	[[clang::always_inline]] foo(); // attempts to inline foo
404	[[clang::always_inline]] i = bar(); // attempts to inline bar
405	[[clang::always_inline]] return f(42, baz(bar())); // attempts to inline everything
406	}
407
408	A declaration statement, which is a statement, is not a statement that can have an
409	attribute associated with it (the attribute applies to the declaration, not the
410	statement in that case). So this use case will not work:
411
412	.. code-block:: c
413
414	int example(void) {
415	[[clang::always_inline]] int i = bar();
416	return i;
417	}
418
419	This attribute does not guarantee that inline substitution actually occurs.
420
421	<ins>Note: applying this attribute to a coroutine at the `-O0` optimization level
422	has no effect; other optimization levels may only partially inline and result in a
423	diagnostic.</ins>
424
425	See also `the Microsoft Docs on Inline Functions`_, `the GCC Common Function
426	Attribute docs`_, and `the GCC Inline docs`_.
427
428	.. _the Microsoft Docs on Inline Functions: https://docs.microsoft.com/en-us/cpp/cpp/inline-functions-cpp
429	.. _the GCC Common Function Attribute docs: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
430	.. _the GCC Inline docs: https://gcc.gnu.org/onlinedocs/gcc/Inline.html)reST";
431
432	static const char AttrDoc_AnalyzerNoReturn[] = R"reST(No documentation.)reST";
433
434	static const char AttrDoc_Annotate[] = R"reST(No documentation.)reST";
435
436	static const char AttrDoc_AnnotateType[] = R"reST(This attribute is used to add annotations to types, typically for use by static
437	analysis tools that are not integrated into the core Clang compiler (e.g.,
438	Clang-Tidy checks or out-of-tree Clang-based tools). It is a counterpart to the
439	`annotate` attribute, which serves the same purpose, but for declarations.
440
441	The attribute takes a mandatory string literal argument specifying the
442	annotation category and an arbitrary number of optional arguments that provide
443	additional information specific to the annotation category. The optional
444	arguments must be constant expressions of arbitrary type.
445
446	For example:
447
448	.. code-block:: c++
449
450	int* [[clang::annotate_type("category1", "foo", 1)]] f(int[[clang::annotate_type("category2")]] *);
451
452	The attribute does not have any effect on the semantics of the type system,
453	neither type checking rules, nor runtime semantics. In particular:
454
455	- ``std::is_same<T, T [[clang::annotate_type("foo")]]>`` is true for all types
456	``T``.
457
458	- It is not permissible for overloaded functions or template specializations
459	to differ merely by an ``annotate_type`` attribute.
460
461	- The presence of an ``annotate_type`` attribute will not affect name
462	mangling.)reST";
463
464	static const char AttrDoc_AnyX86Interrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt))`` attribute on X86
465	targets. This attribute may be attached to a function definition and instructs
466	the backend to generate appropriate function entry/exit code so that it can be
467	used directly as an interrupt service routine.
468
469	Interrupt handlers have access to the stack frame pushed onto the stack by the processor,
470	and return using the ``IRET`` instruction. All registers in an interrupt handler are callee-saved.
471	Exception handlers also have access to the error code pushed onto the stack by the processor,
472	when applicable.
473
474	An interrupt handler must take the following arguments:
475
476	.. code-block:: c
477
478	__attribute__ ((interrupt))
479	void f (struct stack_frame *frame) {
480	...
481	}
482
483	Where ``struct stack_frame`` is a suitable struct matching the stack frame pushed by the
484	processor.
485
486	An exception handler must take the following arguments:
487
488	.. code-block:: c
489
490	__attribute__ ((interrupt))
491	void g (struct stack_frame *frame, unsigned long code) {
492	...
493	}
494
495	On 32-bit targets, the ``code`` argument should be of type ``unsigned int``.
496
497	Exception handlers should only be used when an error code is pushed by the processor.
498	Using the incorrect handler type will crash the system.
499
500	Interrupt and exception handlers cannot be called by other functions and must have return type ``void``.
501
502	Interrupt and exception handlers should only call functions with the 'no_caller_saved_registers'
503	attribute, or should be compiled with the '-mgeneral-regs-only' flag to avoid saving unused
504	non-GPR registers.)reST";
505
506	static const char AttrDoc_AnyX86NoCallerSavedRegisters[] = R"reST(Use this attribute to indicate that the specified function has no
507	caller-saved registers. That is, all registers are callee-saved except for
508	registers used for passing parameters to the function or returning parameters
509	from the function.
510	The compiler saves and restores any modified registers that were not used for
511	passing or returning arguments to the function.
512
513	The user can call functions specified with the 'no_caller_saved_registers'
514	attribute from an interrupt handler without saving and restoring all
515	call-clobbered registers.
516
517	Functions specified with the 'no_caller_saved_registers' attribute should only
518	call other functions with the 'no_caller_saved_registers' attribute, or should be
519	compiled with the '-mgeneral-regs-only' flag to avoid saving unused non-GPR registers.
520
521	Note that 'no_caller_saved_registers' attribute is not a calling convention.
522	In fact, it only overrides the decision of which registers should be saved by
523	the caller, but not how the parameters are passed from the caller to the callee.
524
525	For example:
526
527	.. code-block:: c
528
529	__attribute__ ((no_caller_saved_registers, fastcall))
530	void f (int arg1, int arg2) {
531	...
532	}
533
534	In this case parameters 'arg1' and 'arg2' will be passed in registers.
535	In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
536	register parameters. However, it will not assume any scratch registers and
537	should save and restore any modified registers except for ECX and EDX.)reST";
538
539	static const char AttrDoc_AnyX86NoCfCheck[] = R"reST(Jump Oriented Programming attacks rely on tampering with addresses used by
540	indirect call / jmp, e.g. redirect control-flow to non-programmer
541	intended bytes in the binary.
542	X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
543	Enforcement Technology (CET). IBT instruments ENDBR instructions used to
544	specify valid targets of indirect call / jmp.
545	The ``nocf_check`` attribute has two roles:
546	1. Appertains to a function - do not add ENDBR instruction at the beginning of
547	the function.
548	2. Appertains to a function pointer - do not track the target function of this
549	pointer (by adding nocf_check prefix to the indirect-call instruction).)reST";
550
551	static const char AttrDoc_ArcWeakrefUnavailable[] = R"reST(No documentation.)reST";
552
553	static const char AttrDoc_ArgumentWithTypeTag[] = R"reST(Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
554	type_tag_idx)))`` on a function declaration to specify that the function
555	accepts a type tag that determines the type of some other argument.
556
557	This attribute is primarily useful for checking arguments of variadic functions
558	(``pointer_with_type_tag`` can be used in most non-variadic cases).
559
560	In the attribute prototype above:
561	* ``arg_kind`` is an identifier that should be used when annotating all
562	applicable type tags.
563	* ``arg_idx`` provides the position of a function argument. The expected type of
564	this function argument will be determined by the function argument specified
565	by ``type_tag_idx``. In the code example below, "3" means that the type of the
566	function's third argument will be determined by ``type_tag_idx``.
567	* ``type_tag_idx`` provides the position of a function argument. This function
568	argument will be a type tag. The type tag will determine the expected type of
569	the argument specified by ``arg_idx``. In the code example below, "2" means
570	that the type tag associated with the function's second argument should agree
571	with the type of the argument specified by ``arg_idx``.
572
573	For example:
574
575	.. code-block:: c++
576
577	int fcntl(int fd, int cmd, ...)
578	__attribute__(( argument_with_type_tag(fcntl,3,2) ));
579	// The function's second argument will be a type tag; this type tag will
580	// determine the expected type of the function's third argument.)reST";
581
582	static const char AttrDoc_ArmAgnostic[] = R"reST(The ``__arm_agnostic`` keyword applies to prototyped function types and
583	affects the function's calling convention for a given state S. This
584	attribute allows the user to describe a function that preserves S, without
585	requiring the function to share S with its callers and without making
586	the assumption that S exists.
587
588	If a function has the ``__arm_agnostic(S)`` attribute and calls a function
589	without this attribute, then the function's object code will contain code
590	to preserve state S. Otherwise, the function's object code will be the same
591	as if it did not have the attribute.
592
593	The attribute takes string arguments to describe state S. The supported
594	states are:
595
596	* ``"sme_za_state"`` for state enabled by PSTATE.ZA, such as ZA and ZT0.
597
598	The attribute ``__arm_agnostic("sme_za_state")`` cannot be used in conjunction
599	with ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` or
600	``__arm_preserves(S)`` where state S describes state enabled by PSTATE.ZA,
601	such as "za" or "zt0".)reST";
602
603	static const char AttrDoc_ArmBuiltinAlias[] = R"reST(This attribute is used in the implementation of the ACLE intrinsics.
604	It allows the intrinsic functions to
605	be declared using the names defined in ACLE, and still be recognized
606	as clang builtins equivalent to the underlying name. For example,
607	``arm_mve.h`` declares the function ``vaddq_u32`` with
608	``__attribute__((__clang_arm_mve_alias(__builtin_arm_mve_vaddq_u32)))``,
609	and similarly, one of the type-overloaded declarations of ``vaddq``
610	will have the same attribute. This ensures that both functions are
611	recognized as that clang builtin, and in the latter case, the choice
612	of which builtin to identify the function as can be deferred until
613	after overload resolution.
614
615	This attribute can only be used to set up the aliases for certain Arm
616	intrinsic functions; it is intended for use only inside ``arm_*.h``
617	and is not a general mechanism for declaring arbitrary aliases for
618	clang builtin functions.
619
620	In order to avoid duplicating the attribute definitions for similar
621	purpose for other architecture, there is a general form for the
622	attribute `clang_builtin_alias`.)reST";
623
624	static const char AttrDoc_ArmIn[] = R"reST(The ``__arm_in`` keyword applies to prototyped function types and specifies
625	that the function shares a given state S with its caller. For ``__arm_in``, the
626	function takes the state S as input and returns with the state S unchanged.
627
628	The attribute takes string arguments to instruct the compiler which state
629	is shared. The supported states for S are:
630
631	* ``"za"`` for Matrix Storage (requires SME)
632
633	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
634	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
635
636	static const char AttrDoc_ArmInOut[] = R"reST(The ``__arm_inout`` keyword applies to prototyped function types and specifies
637	that the function shares a given state S with its caller. For ``__arm_inout``,
638	the function takes the state S as input and returns new state for S.
639
640	The attribute takes string arguments to instruct the compiler which state
641	is shared. The supported states for S are:
642
643	* ``"za"`` for Matrix Storage (requires SME)
644
645	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
646	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
647
648	static const char AttrDoc_ArmLocallyStreaming[] = R"reST(The ``__arm_locally_streaming`` keyword applies to function declarations
649	and specifies that all the statements in the function are executed in
650	streaming mode. This means that:
651
652	* the function requires that the target processor implements the Scalable Matrix
653	Extension (SME).
654
655	* the program automatically puts the machine into streaming mode before
656	executing the statements and automatically restores the previous mode
657	afterwards.
658
659	Clang manages PSTATE.SM automatically; it is not the source code's
660	responsibility to do this. For example, Clang will emit code to enable
661	streaming mode at the start of the function, and disable streaming mode
662	at the end of the function.)reST";
663
664	static const char AttrDoc_ArmMveStrictPolymorphism[] = R"reST(This attribute is used in the implementation of the ACLE intrinsics for the Arm
665	MVE instruction set. It is used to define the vector types used by the MVE
666	intrinsics.
667
668	Its effect is to modify the behavior of a vector type with respect to function
669	overloading. If a candidate function for overload resolution has a parameter
670	type with this attribute, then the selection of that candidate function will be
671	disallowed if the actual argument can only be converted via a lax vector
672	conversion. The aim is to prevent spurious ambiguity in ARM MVE polymorphic
673	intrinsics.
674
675	.. code-block:: c++
676
677	void overloaded(uint16x8_t vector, uint16_t scalar);
678	void overloaded(int32x4_t vector, int32_t scalar);
679	uint16x8_t myVector;
680	uint16_t myScalar;
681
682	// myScalar is promoted to int32_t as a side effect of the addition,
683	// so if lax vector conversions are considered for myVector, then
684	// the two overloads are equally good (one argument conversion
685	// each). But if the vector has the __clang_arm_mve_strict_polymorphism
686	// attribute, only the uint16x8_t,uint16_t overload will match.
687	overloaded(myVector, myScalar + 1);
688
689	However, this attribute does not prohibit lax vector conversions in contexts
690	other than overloading.
691
692	.. code-block:: c++
693
694	uint16x8_t function();
695
696	// This is still permitted with lax vector conversion enabled, even
697	// if the vector types have __clang_arm_mve_strict_polymorphism
698	int32x4_t result = function();)reST";
699
700	static const char AttrDoc_ArmNew[] = R"reST(The ``__arm_new`` keyword applies to function declarations and specifies
701	that the function will create a new scope for state S.
702
703	The attribute takes string arguments to instruct the compiler for which state
704	to create new scope. The supported states for S are:
705
706	* ``"za"`` for Matrix Storage (requires SME)
707
708	For state ``"za"``, this means that:
709
710	* the function requires that the target processor implements the Scalable Matrix
711	Extension (SME).
712
713	* the function will commit any lazily saved ZA data.
714
715	* the function will create a new ZA context and enable PSTATE.ZA.
716
717	* the function will disable PSTATE.ZA (by setting it to 0) before returning.
718
719	For ``__arm_new("za")`` functions Clang will set up the ZA context automatically
720	on entry to the function and disable it before returning. For example, if ZA is
721	in a dormant state Clang will generate the code to commit a lazy-save and set up
722	a new ZA state before executing user code.)reST";
723
724	static const char AttrDoc_ArmOut[] = R"reST(The ``__arm_out`` keyword applies to prototyped function types and specifies
725	that the function shares a given state S with its caller. For ``__arm_out``,
726	the function ignores the incoming state for S and returns new state for S.
727
728	The attribute takes string arguments to instruct the compiler which state
729	is shared. The supported states for S are:
730
731	* ``"za"`` for Matrix Storage (requires SME)
732
733	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
734	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
735
736	static const char AttrDoc_ArmPreserves[] = R"reST(The ``__arm_preserves`` keyword applies to prototyped function types and
737	specifies that the function does not read a given state S and returns
738	with state S unchanged.
739
740	The attribute takes string arguments to instruct the compiler which state
741	is shared. The supported states for S are:
742
743	* ``"za"`` for Matrix Storage (requires SME)
744
745	The attributes ``__arm_in(S)``, ``__arm_out(S)``, ``__arm_inout(S)`` and
746	``__arm_preserves(S)`` are all mutually exclusive for the same state S.)reST";
747
748	static const char AttrDoc_ArmStreaming[] = R"reST(The ``__arm_streaming`` keyword applies to prototyped function types and specifies
749	that the function has a "streaming interface". This means that:
750
751	* the function requires that the processor implements the Scalable Matrix
752	Extension (SME).
753
754	* the function must be entered in streaming mode (that is, with PSTATE.SM
755	set to 1)
756
757	* the function must return in streaming mode
758
759	Clang manages PSTATE.SM automatically; it is not the source code's
760	responsibility to do this. For example, if a non-streaming
761	function calls an ``__arm_streaming`` function, Clang generates code
762	that switches into streaming mode before calling the function and
763	switches back to non-streaming mode on return.)reST";
764
765	static const char AttrDoc_ArmStreamingCompatible[] = R"reST(The ``__arm_streaming_compatible`` keyword applies to prototyped function types and
766	specifies that the function has a "streaming compatible interface". This
767	means that:
768
769	* the function may be entered in either non-streaming mode (PSTATE.SM=0) or
770	in streaming mode (PSTATE.SM=1).
771
772	* the function must return in the same mode as it was entered.
773
774	* the code executed in the function is compatible with either mode.
775
776	Clang manages PSTATE.SM automatically; it is not the source code's
777	responsibility to do this. Clang will ensure that the generated code in
778	streaming-compatible functions is valid in either mode (PSTATE.SM=0 or
779	PSTATE.SM=1). For example, if an ``__arm_streaming_compatible`` function calls a
780	non-streaming function, Clang generates code to temporarily switch out of streaming
781	mode before calling the function and switch back to streaming-mode on return if
782	``PSTATE.SM`` is ``1`` on entry of the caller. If ``PSTATE.SM`` is ``0`` on
783	entry to the ``__arm_streaming_compatible`` function, the call will be executed
784	without changing modes.)reST";
785
786	static const char AttrDoc_Artificial[] = R"reST(The ``artificial`` attribute can be applied to an inline function. If such a
787	function is inlined, the attribute indicates that debuggers should associate
788	the resulting instructions with the call site, rather than with the
789	corresponding line within the inlined callee.)reST";
790
791	static const char AttrDoc_AsmLabel[] = R"reST(This attribute can be used on a function or variable to specify its symbol name.
792
793	On some targets, all C symbols are prefixed by default with a single character,
794	typically ``_``. This was done historically to distinguish them from symbols
795	used by other languages. (This prefix is also added to the standard Itanium
796	C++ ABI prefix on "mangled" symbol names, so that e.g. on such targets the true
797	symbol name for a C++ variable declared as ``int cppvar;`` would be
798	``__Z6cppvar``; note the two underscores.) This prefix is not added to the
799	symbol names specified by the ``__asm`` attribute; programmers wishing to match
800	a C symbol name must compensate for this.
801
802	For example, consider the following C code:
803
804	.. code-block:: c
805
806	int var1 __asm("altvar") = 1; // "altvar" in symbol table.
807	int var2 = 1; // "_var2" in symbol table.
808
809	void func1(void) __asm("altfunc");
810	void func1(void) {} // "altfunc" in symbol table.
811	void func2(void) {} // "_func2" in symbol table.
812
813	Clang's implementation of this attribute is compatible with GCC's, `documented here <https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html>`_.
814
815	While it is possible to use this attribute to name a special symbol used
816	internally by the compiler, such as an LLVM intrinsic, this is neither
817	recommended nor supported and may cause the compiler to crash or miscompile.
818	Users who wish to gain access to intrinsic behavior are strongly encouraged to
819	request new builtin functions.)reST";
820
821	static const char AttrDoc_AssertCapability[] = R"reST(Marks a function that dynamically tests whether a capability is held, and halts
822	the program if it is not held.)reST";
823
824	static const char AttrDoc_AssumeAligned[] = R"reST(Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function
825	declaration to specify that the return value of the function (which must be a
826	pointer type) has the specified offset, in bytes, from an address with the
827	specified alignment. The offset is taken to be zero if omitted.
828
829	.. code-block:: c++
830
831	// The returned pointer value has 32-byte alignment.
832	void *a() __attribute__((assume_aligned (32)));
833
834	// The returned pointer value is 4 bytes greater than an address having
835	// 32-byte alignment.
836	void *b() __attribute__((assume_aligned (32, 4)));
837
838	Note that this attribute provides information to the compiler regarding a
839	condition that the code already ensures is true. It does not cause the compiler
840	to enforce the provided alignment assumption.)reST";
841
842	static const char AttrDoc_Atomic[] = R"reST(The ``atomic`` attribute can be applied to compound statements to override or
843	further specify the default atomic code-generation behavior, especially on
844	targets such as AMDGPU. You can annotate compound statements with options
845	to modify how atomic instructions inside that statement are emitted at the IR
846	level.
847
848	For details, see the documentation for `@atomic
849	<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-controlling-atomic-code-generation>`_)reST";
850
851	static const char AttrDoc_Availability[] = R"reST(The ``availability`` attribute can be placed on declarations to describe the
852	lifecycle of that declaration relative to operating system versions. Consider
853	the function declaration for a hypothetical function ``f``:
854
855	.. code-block:: c++
856
857	void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
858
859	The availability attribute states that ``f`` was introduced in macOS 10.4,
860	deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
861	is used by Clang to determine when it is safe to use ``f``: for example, if
862	Clang is instructed to compile code for macOS 10.5, a call to ``f()``
863	succeeds. If Clang is instructed to compile code for macOS 10.6, the call
864	succeeds but Clang emits a warning specifying that the function is deprecated.
865	Finally, if Clang is instructed to compile code for macOS 10.7, the call
866	fails because ``f()`` is no longer available.
867
868	Clang is instructed to compile code for a minimum deployment version using
869	the ``-target`` or ``-mtargetos`` command line arguments. For example,
870	macOS 10.7 would be specified as ``-target x86_64-apple-macos10.7`` or
871	``-mtargetos=macos10.7``. Variants like Mac Catalyst are specified as
872	``-target arm64-apple-ios15.0-macabi`` or ``-mtargetos=ios15.0-macabi``
873
874	The availability attribute is a comma-separated list starting with the
875	platform name and then including clauses specifying important milestones in the
876	declaration's lifetime (in any order) along with additional information. Those
877	clauses can be:
878
879	introduced=\ version
880	The first version in which this declaration was introduced.
881
882	deprecated=\ version
883	The first version in which this declaration was deprecated, meaning that
884	users should migrate away from this API.
885
886	obsoleted=\ version
887	The first version in which this declaration was obsoleted, meaning that it
888	was removed completely and can no longer be used.
889
890	unavailable
891	This declaration is never available on this platform.
892
893	message=\ string-literal
894	Additional message text that Clang will provide when emitting a warning or
895	error about use of a deprecated or obsoleted declaration. Useful to direct
896	users to replacement APIs.
897
898	replacement=\ string-literal
899	Additional message text that Clang will use to provide Fix-It when emitting
900	a warning about use of a deprecated declaration. The Fix-It will replace
901	the deprecated declaration with the new declaration specified.
902
903	environment=\ identifier
904	Target environment in which this declaration is available. If present,
905	the availability attribute applies only to targets with the same platform
906	and environment. The parameter is currently supported only in HLSL.
907
908	Multiple availability attributes can be placed on a declaration, which may
909	correspond to different platforms. For most platforms, the availability
910	attribute with the platform corresponding to the target platform will be used;
911	any others will be ignored. However, the availability for ``watchOS`` and
912	``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute.
913	Any explicit availability attributes for those platforms are still preferred over
914	the implicitly inferred availability attributes. If no availability attribute
915	specifies availability for the current target platform, the availability
916	attributes are ignored. Supported platforms are:
917
918	``iOS``
919	``macOS``
920	``tvOS``
921	``watchOS``
922	``iOSApplicationExtension``
923	``macOSApplicationExtension``
924	``tvOSApplicationExtension``
925	``watchOSApplicationExtension``
926	``macCatalyst``
927	``macCatalystApplicationExtension``
928	``visionOS``
929	``visionOSApplicationExtension``
930	``driverkit``
931	``swift``
932	``android``
933	``fuchsia``
934	``ohos``
935	``zos``
936	``ShaderModel``
937
938	Some platforms have alias names:
939
940	``ios``
941	``macos``
942	``macosx (deprecated)``
943	``tvos``
944	``watchos``
945	``ios_app_extension``
946	``macos_app_extension``
947	``macosx_app_extension (deprecated)``
948	``tvos_app_extension``
949	``watchos_app_extension``
950	``maccatalyst``
951	``maccatalyst_app_extension``
952	``visionos``
953	``visionos_app_extension``
954	``shadermodel``
955
956	Supported environment names for the ShaderModel platform:
957
958	``pixel``
959	``vertex``
960	``geometry``
961	``hull``
962	``domain``
963	``compute``
964	``raygeneration``
965	``intersection``
966	``anyhit``
967	``closesthit``
968	``miss``
969	``callable``
970	``mesh``
971	``amplification``
972	``library``
973
974	A declaration can typically be used even when deploying back to a platform
975	version prior to when the declaration was introduced. When this happens, the
976	declaration is `weakly linked
977	<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
978	as if the ``weak_import`` attribute were added to the declaration. A
979	weakly-linked declaration may or may not be present a run-time, and a program
980	can determine whether the declaration is present by checking whether the
981	address of that declaration is non-NULL.
982
983	The flag ``strict`` disallows using API when deploying back to a
984	platform version prior to when the declaration was introduced. An
985	attempt to use such API before its introduction causes a hard error.
986	Weakly-linking is almost always a better API choice, since it allows
987	users to query availability at runtime.
988
989	If there are multiple declarations of the same entity, the availability
990	attributes must either match on a per-platform basis or later
991	declarations must not have availability attributes for that
992	platform. For example:
993
994	.. code-block:: c
995
996	void g(void) __attribute__((availability(macos,introduced=10.4)));
997	void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
998	void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
999	void g(void); // okay, inherits both macos and ios availability from above.
1000	void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
1001
1002	When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
1003
1004	.. code-block:: objc
1005
1006	@interface A
1007	- (id)method __attribute__((availability(macos,introduced=10.4)));
1008	- (id)method2 __attribute__((availability(macos,introduced=10.4)));
1009	@end
1010
1011	@interface B : A
1012	- (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
1013	- (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
1014	@end
1015
1016	Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
1017	``<os/availability.h>`` can simplify the spelling:
1018
1019	.. code-block:: objc
1020
1021	@interface A
1022	- (id)method API_AVAILABLE(macos(10.11)));
1023	- (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
1024	@end
1025
1026	Availability attributes can also be applied using a ``#pragma clang attribute``.
1027	Any explicit availability attribute whose platform corresponds to the target
1028	platform is applied to a declaration regardless of the availability attributes
1029	specified in the pragma. For example, in the code below,
1030	``hasExplicitAvailabilityAttribute`` will use the ``macOS`` availability
1031	attribute that is specified with the declaration, whereas
1032	``getsThePragmaAvailabilityAttribute`` will use the ``macOS`` availability
1033	attribute that is applied by the pragma.
1034
1035	.. code-block:: c
1036
1037	#pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)
1038	void getsThePragmaAvailabilityAttribute(void);
1039	void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4)));
1040	#pragma clang attribute pop
1041
1042	For platforms like ``watchOS`` and ``tvOS``, whose availability attributes can
1043	be implicitly inferred from an ``iOS`` availability attribute, the logic is
1044	slightly more complex. The explicit and the pragma-applied availability
1045	attributes whose platform corresponds to the target platform are applied as
1046	described in the previous paragraph. However, the implicitly inferred attributes
1047	are applied to a declaration only when there is no explicit or pragma-applied
1048	availability attribute whose platform corresponds to the target platform. For
1049	example, the function below will receive the ``tvOS`` availability from the
1050	pragma rather than using the inferred ``iOS`` availability from the declaration:
1051
1052	.. code-block:: c
1053
1054	#pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)
1055	void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0)));
1056	#pragma clang attribute pop
1057
1058	The compiler is also able to apply implicitly inferred attributes from a pragma
1059	as well. For example, when targeting ``tvOS``, the function below will receive
1060	a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS``
1061	availability attribute applied by the pragma:
1062
1063	.. code-block:: c
1064
1065	#pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)
1066	void infersTVOSAvailabilityFromPragma(void);
1067	#pragma clang attribute pop
1068
1069	The implicit attributes that are inferred from explicitly specified attributes
1070	whose platform corresponds to the target platform are applied to the declaration
1071	even if there is an availability attribute that can be inferred from a pragma.
1072	For example, the function below will receive the ``tvOS, introduced=11.0``
1073	availability that is inferred from the attribute on the declaration rather than
1074	inferring availability from the pragma:
1075
1076	.. code-block:: c
1077
1078	#pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)
1079	void infersTVOSAvailabilityFromAttributeNextToDeclaration(void)
1080	__attribute__((availability(iOS,introduced=11.0)));
1081	#pragma clang attribute pop
1082
1083	Also see the documentation for `@available
1084	<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_)reST";
1085
1086	static const char AttrDoc_AvailableOnlyInDefaultEvalMethod[] = R"reST(No documentation.)reST";
1087
1088	static const char AttrDoc_BPFFastCall[] = R"reST(Functions annotated with this attribute are likely to be inlined by BPF JIT.
1089	It is assumed that inlined implementation uses less caller saved registers,
1090	than a regular function.
1091	Specifically, the following registers are likely to be preserved:
1092	- ``R0`` if function return value is ``void``;
1093	- ``R2-R5` if function takes 1 argument;
1094	- ``R3-R5` if function takes 2 arguments;
1095	- ``R4-R5` if function takes 3 arguments;
1096	- ``R5`` if function takes 4 arguments;
1097
1098	For such functions Clang generates code pattern that allows BPF JIT
1099	to recognize and remove unnecessary spills and fills of the preserved
1100	registers.)reST";
1101
1102	static const char AttrDoc_BPFPreserveAccessIndex[] = R"reST(Clang supports the ``__attribute__((preserve_access_index))``
1103	attribute for the BPF target. This attribute may be attached to a
1104	struct or union declaration, where if -g is specified, it enables
1105	preserving struct or union member access debuginfo indices of this
1106	struct or union, similar to clang ``__builtin_preserve_access_index()``.)reST";
1107
1108	static const char AttrDoc_BPFPreserveStaticOffset[] = R"reST(Clang supports the ``__attribute__((preserve_static_offset))``
1109	attribute for the BPF target. This attribute may be attached to a
1110	struct or union declaration. Reading or writing fields of types having
1111	such annotation is guaranteed to generate LDX/ST/STX instruction with
1112	offset corresponding to the field.
1113
1114	For example:
1115
1116	.. code-block:: c
1117
1118	struct foo {
1119	int a;
1120	int b;
1121	};
1122
1123	struct bar {
1124	int a;
1125	struct foo b;
1126	} __attribute__((preserve_static_offset));
1127
1128	void buz(struct bar *g) {
1129	g->b.a = 42;
1130	}
1131
1132	The assignment to ``g``'s field would produce an ST instruction with
1133	offset 8: ``*(u32)(r1 + 8) = 42;``.
1134
1135	Without this attribute generated instructions might be different,
1136	depending on optimizations behavior. E.g. the example above could be
1137	rewritten as ``r1 += 8; *(u32)(r1 + 0) = 42;``.)reST";
1138
1139	static const char AttrDoc_BTFDeclTag[] = R"reST(Clang supports the ``__attribute__((btf_decl_tag("ARGUMENT")))`` attribute for
1140	all targets. This attribute may be attached to a struct/union, struct/union
1141	field, function, function parameter, variable or typedef declaration. If -g is
1142	specified, the ``ARGUMENT`` info will be preserved in IR and be emitted to
1143	dwarf. For BPF targets, the ``ARGUMENT`` info will be emitted to .BTF ELF
1144	section too.)reST";
1145
1146	static const char AttrDoc_BTFTypeTag[] = R"reST(Clang supports the ``__attribute__((btf_type_tag("ARGUMENT")))`` attribute for
1147	all targets. It only has effect when ``-g`` is specified on the command line and
1148	is currently silently ignored when not applied to a pointer type (note: this
1149	scenario may be diagnosed in the future).
1150
1151	The ``ARGUMENT`` string will be preserved in IR and emitted to DWARF for the
1152	types used in variable declarations, function declarations, or typedef
1153	declarations.
1154
1155	For BPF targets, the ``ARGUMENT`` string will also be emitted to .BTF ELF
1156	section.)reST";
1157
1158	static const char AttrDoc_Blocking[] = R"reST(Declares that a function potentially blocks, and prevents any potential inference of ``nonblocking``
1159	by the compiler.)reST";
1160
1161	static const char AttrDoc_Blocks[] = R"reST(No documentation.)reST";
1162
1163	static const char AttrDoc_Builtin[] = R"reST()reST";
1164
1165	static const char AttrDoc_BuiltinAlias[] = R"reST(This attribute is used in the implementation of the C intrinsics.
1166	It allows the C intrinsic functions to be declared using the names defined
1167	in target builtins, and still be recognized as clang builtins equivalent to the
1168	underlying name. For example, ``riscv_vector.h`` declares the function ``vadd``
1169	with ``__attribute__((clang_builtin_alias(__builtin_rvv_vadd_vv_i8m1)))``.
1170	This ensures that both functions are recognized as that clang builtin,
1171	and in the latter case, the choice of which builtin to identify the
1172	function as can be deferred until after overload resolution.
1173
1174	This attribute can only be used to set up the aliases for certain ARM/RISC-V
1175	C intrinsic functions; it is intended for use only inside ``arm_*.h`` and
1176	``riscv_*.h`` and is not a general mechanism for declaring arbitrary aliases
1177	for clang builtin functions.)reST";
1178
1179	static const char AttrDoc_C11NoReturn[] = R"reST(A function declared as ``_Noreturn`` shall not return to its caller. The
1180	compiler will generate a diagnostic for a function declared as ``_Noreturn``
1181	that appears to be capable of returning to its caller. Despite being a type
1182	specifier, the ``_Noreturn`` attribute cannot be specified on a function
1183	pointer type.)reST";
1184
1185	static const char AttrDoc_CDecl[] = R"reST(No documentation.)reST";
1186
1187	static const char AttrDoc_CFAuditedTransfer[] = R"reST(No documentation.)reST";
1188
1189	static const char AttrDoc_CFConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1190	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1191	convention (e.g. functions starting with "get" are assumed to return at
1192	``+0``).
1193
1194	It can be overridden using a family of the following attributes. In
1195	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1196	a function communicates that the object is returned at ``+1``, and the caller
1197	is responsible for freeing it.
1198	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1199	specifies that the object is returned at ``+0`` and the ownership remains with
1200	the callee.
1201	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1202	the Objective-C method call consumes the reference to ``self``, e.g. by
1203	attaching it to a supplied parameter.
1204	Additionally, parameters can have an annotation
1205	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1206	as that parameter effectively transfers the ownership, and the caller is no
1207	longer responsible for it.
1208	These attributes affect code generation when interacting with ARC code, and
1209	they are used by the Clang Static Analyzer.
1210
1211	In C programs using CoreFoundation, a similar set of attributes:
1212	``__attribute__((cf_returns_not_retained))``,
1213	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1214	have the same respective semantics when applied to CoreFoundation objects.
1215	These attributes affect code generation when interacting with ARC code, and
1216	they are used by the Clang Static Analyzer.
1217
1218	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1219	the same attribute family is present:
1220	``__attribute__((os_returns_not_retained))``,
1221	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1222	with the same respective semantics.
1223	Similar to ``__attribute__((ns_consumes_self))``,
1224	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1225	the reference to "this" (e.g., when attaching it to a different object supplied
1226	as a parameter).
1227	Out parameters (parameters the function is meant to write into,
1228	either via pointers-to-pointers or references-to-pointers)
1229	may be annotated with ``__attribute__((os_returns_retained))``
1230	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1231	written into the out parameter should (or respectively should not) be released
1232	after use.
1233	Since often out parameters may or may not be written depending on the exit
1234	code of the function,
1235	annotations ``__attribute__((os_returns_retained_on_zero))``
1236	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1237	an out parameter at ``+1`` is written if and only if the function returns a zero
1238	(respectively non-zero) error code.
1239	Observe that return-code-dependent out parameter annotations are only
1240	available for retained out parameters, as non-retained object do not have to be
1241	released by the callee.
1242	These attributes are only used by the Clang Static Analyzer.
1243
1244	The family of attributes ``X_returns_X_retained`` can be added to functions,
1245	C++ methods, and Objective-C methods and properties.
1246	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1247	and Objective-C methods.)reST";
1248
1249	static const char AttrDoc_CFGuard[] = R"reST(Code can indicate CFG checks are not wanted with the ``__declspec(guard(nocf))``
1250	attribute. This directs the compiler to not insert any CFG checks for the entire
1251	function. This approach is typically used only sparingly in specific situations
1252	where the programmer has manually inserted "CFG-equivalent" protection. The
1253	programmer knows that they are calling through some read-only function table
1254	whose address is obtained through read-only memory references and for which the
1255	index is masked to the function table limit. This approach may also be applied
1256	to small wrapper functions that are not inlined and that do nothing more than
1257	make a call through a function pointer. Since incorrect usage of this directive
1258	can compromise the security of CFG, the programmer must be very careful using
1259	the directive. Typically, this usage is limited to very small functions that
1260	only call one function.
1261
1262	`Control Flow Guard documentation <https://docs.microsoft.com/en-us/windows/win32/secbp/pe-metadata>`)reST";
1263
1264	static const char AttrDoc_CFICanonicalJumpTable[] = R"reST(Use ``__attribute__((cfi_canonical_jump_table))`` on a function declaration to
1265	make the function's CFI jump table canonical. See :ref:`the CFI documentation
1266	<cfi-canonical-jump-tables>` for more details.)reST";
1267
1268	static const char AttrDoc_CFISalt[] = R"reST(The ``cfi_salt`` attribute specifies a string literal that is used as a salt
1269	for Control-Flow Integrity (CFI) checks to distinguish between functions with
1270	the same type signature. This attribute can be applied to function declarations,
1271	function definitions, and function pointer typedefs.
1272
1273	The attribute prevents function pointers from being replaced with pointers to
1274	functions that have a compatible type, which can be a CFI bypass vector.
1275
1276	Syntax:
1277
1278	* GNU-style: ``__attribute__((cfi_salt("<salt_string>")))``
1279	* C++11-style: ``[[clang::cfi_salt("<salt_string>")]]``
1280
1281	Usage:
1282
1283	The attribute takes a single string literal argument that serves as the salt.
1284	Functions or function types with different salt values will have different CFI
1285	hashes, even if they have identical type signatures.
1286
1287	Motivation:
1288
1289	In large codebases like the Linux kernel, there are often hundreds of functions
1290	with identical type signatures that are called indirectly:
1291
1292	.. code-block::
1293
1294	1662 functions with void (*)(void)
1295	1179 functions with int (*)(void)
1296	...
1297
1298	By salting the CFI hashes, you can make CFI more robust by ensuring that
1299	functions intended for different purposes have distinct CFI identities.
1300
1301	Type Compatibility:
1302
1303	* Functions with different salt values are considered to have incompatible types
1304	* Function pointers with different salt values cannot be assigned to each other
1305	* All declarations of the same function must use the same salt value
1306
1307	Example:
1308
1309	.. code-block:: c
1310
1311	// Header file - define convenience macros
1312	#define __cfi_salt(s) __attribute__((cfi_salt(s)))
1313
1314	// Typedef for regular function pointers
1315	typedef int (*fptr_t)(void);
1316
1317	// Typedef for salted function pointers
1318	typedef int (*fptr_salted_t)(void) __cfi_salt("pepper");
1319
1320	struct widget_ops {
1321	fptr_t init; // Regular CFI
1322	fptr_salted_t exec; // Salted CFI
1323	fptr_t cleanup; // Regular CFI
1324	};
1325
1326	// Function implementations
1327	static int widget_init(void) { return 0; }
1328	static int widget_exec(void) __cfi_salt("pepper") { return 1; }
1329	static int widget_cleanup(void) { return 0; }
1330
1331	static struct widget_ops ops = {
1332	.init = widget_init, // OK - compatible types
1333	.exec = widget_exec, // OK - both use "pepper" salt
1334	.cleanup = widget_cleanup // OK - compatible types
1335	};
1336
1337	// Using C++11 attribute syntax
1338	void secure_callback(void) [[clang::cfi_salt("secure")]];
1339
1340	// This would cause a compilation error:
1341	// fptr_t bad_ptr = widget_exec; // Error: incompatible types
1342
1343	Notes:
1344
1345	* The salt string can contain non-NULL ASCII characters, including spaces and
1346	quotes
1347	* This attribute only applies to function types; using it on non-function
1348	types will generate a warning
1349	* All declarations and definitions of the same function must use identical
1350	salt values
1351	* The attribute affects type compatibility during compilation and CFI hash
1352	generation during code generation)reST";
1353
1354	static const char AttrDoc_CFIUncheckedCallee[] = R"reST(``cfi_unchecked_callee`` is a function type attribute which prevents the compiler from instrumenting
1355	`Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_ checks on indirect
1356	function calls. This also includes control flow checks added by
1357	`-fsanitize=function <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html#available-checks>`.
1358	Specifically, the attribute has the following semantics:
1359
1360	1. Indirect calls to a function type with this attribute will not be instrumented with CFI. That is,
1361	the indirect call will not be checked. Note that this only changes the behavior for indirect calls
1362	on pointers to function types having this attribute. It does not prevent all indirect function calls
1363	for a given type from being checked.
1364	2. All direct references to a function whose type has this attribute will always reference the
1365	function definition rather than an entry in the CFI jump table.
1366	3. When a pointer to a function with this attribute is implicitly cast to a pointer to a function
1367	without this attribute, the compiler will give a warning saying this attribute is discarded. This
1368	warning can be silenced with an explicit cast. Note an explicit cast just disables the warning, so
1369	direct references to a function with a ``cfi_unchecked_callee`` attribute will still reference the
1370	function definition rather than the CFI jump table.
1371
1372	.. code-block:: c
1373
1374	#define CFI_UNCHECKED_CALLEE __attribute__((cfi_unchecked_callee))
1375
1376	void no_cfi() CFI_UNCHECKED_CALLEE {}
1377
1378	void (*with_cfi)() = no_cfi; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
1379	// `with_cfi` also points to the actual definition of `no_cfi` rather than
1380	// its jump table entry.
1381
1382	void invoke(void (CFI_UNCHECKED_CALLEE *func)()) {
1383	func(); // CFI will not instrument this indirect call.
1384
1385	void (*func2)() = func; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
1386
1387	func2(); // CFI will instrument this indirect call. Users should be careful however because if this
1388	// references a function with type `cfi_unchecked_callee`, then the CFI check may incorrectly
1389	// fail because the reference will be to the function definition rather than the CFI jump
1390	// table entry.
1391	}
1392
1393	This attribute can only be applied on functions or member functions. This attribute can be a good
1394	alternative to ``no_sanitize("cfi")`` if you only want to disable innstrumentation for specific indirect
1395	calls rather than applying ``no_sanitize("cfi")`` on the whole function containing indirect call. Note
1396	that ``cfi_unchecked_attribute`` is a type attribute doesn't disable CFI instrumentation on a function
1397	body.)reST";
1398
1399	static const char AttrDoc_CFReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1400	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1401	convention (e.g. functions starting with "get" are assumed to return at
1402	``+0``).
1403
1404	It can be overridden using a family of the following attributes. In
1405	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1406	a function communicates that the object is returned at ``+1``, and the caller
1407	is responsible for freeing it.
1408	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1409	specifies that the object is returned at ``+0`` and the ownership remains with
1410	the callee.
1411	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1412	the Objective-C method call consumes the reference to ``self``, e.g. by
1413	attaching it to a supplied parameter.
1414	Additionally, parameters can have an annotation
1415	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1416	as that parameter effectively transfers the ownership, and the caller is no
1417	longer responsible for it.
1418	These attributes affect code generation when interacting with ARC code, and
1419	they are used by the Clang Static Analyzer.
1420
1421	In C programs using CoreFoundation, a similar set of attributes:
1422	``__attribute__((cf_returns_not_retained))``,
1423	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1424	have the same respective semantics when applied to CoreFoundation objects.
1425	These attributes affect code generation when interacting with ARC code, and
1426	they are used by the Clang Static Analyzer.
1427
1428	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1429	the same attribute family is present:
1430	``__attribute__((os_returns_not_retained))``,
1431	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1432	with the same respective semantics.
1433	Similar to ``__attribute__((ns_consumes_self))``,
1434	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1435	the reference to "this" (e.g., when attaching it to a different object supplied
1436	as a parameter).
1437	Out parameters (parameters the function is meant to write into,
1438	either via pointers-to-pointers or references-to-pointers)
1439	may be annotated with ``__attribute__((os_returns_retained))``
1440	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1441	written into the out parameter should (or respectively should not) be released
1442	after use.
1443	Since often out parameters may or may not be written depending on the exit
1444	code of the function,
1445	annotations ``__attribute__((os_returns_retained_on_zero))``
1446	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1447	an out parameter at ``+1`` is written if and only if the function returns a zero
1448	(respectively non-zero) error code.
1449	Observe that return-code-dependent out parameter annotations are only
1450	available for retained out parameters, as non-retained object do not have to be
1451	released by the callee.
1452	These attributes are only used by the Clang Static Analyzer.
1453
1454	The family of attributes ``X_returns_X_retained`` can be added to functions,
1455	C++ methods, and Objective-C methods and properties.
1456	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1457	and Objective-C methods.)reST";
1458
1459	static const char AttrDoc_CFReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
1460	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
1461	convention (e.g. functions starting with "get" are assumed to return at
1462	``+0``).
1463
1464	It can be overridden using a family of the following attributes. In
1465	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
1466	a function communicates that the object is returned at ``+1``, and the caller
1467	is responsible for freeing it.
1468	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
1469	specifies that the object is returned at ``+0`` and the ownership remains with
1470	the callee.
1471	The annotation ``__attribute__((ns_consumes_self))`` specifies that
1472	the Objective-C method call consumes the reference to ``self``, e.g. by
1473	attaching it to a supplied parameter.
1474	Additionally, parameters can have an annotation
1475	``__attribute__((ns_consumed))``, which specifies that passing an owned object
1476	as that parameter effectively transfers the ownership, and the caller is no
1477	longer responsible for it.
1478	These attributes affect code generation when interacting with ARC code, and
1479	they are used by the Clang Static Analyzer.
1480
1481	In C programs using CoreFoundation, a similar set of attributes:
1482	``__attribute__((cf_returns_not_retained))``,
1483	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
1484	have the same respective semantics when applied to CoreFoundation objects.
1485	These attributes affect code generation when interacting with ARC code, and
1486	they are used by the Clang Static Analyzer.
1487
1488	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
1489	the same attribute family is present:
1490	``__attribute__((os_returns_not_retained))``,
1491	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
1492	with the same respective semantics.
1493	Similar to ``__attribute__((ns_consumes_self))``,
1494	``__attribute__((os_consumes_this))`` specifies that the method call consumes
1495	the reference to "this" (e.g., when attaching it to a different object supplied
1496	as a parameter).
1497	Out parameters (parameters the function is meant to write into,
1498	either via pointers-to-pointers or references-to-pointers)
1499	may be annotated with ``__attribute__((os_returns_retained))``
1500	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
1501	written into the out parameter should (or respectively should not) be released
1502	after use.
1503	Since often out parameters may or may not be written depending on the exit
1504	code of the function,
1505	annotations ``__attribute__((os_returns_retained_on_zero))``
1506	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1507	an out parameter at ``+1`` is written if and only if the function returns a zero
1508	(respectively non-zero) error code.
1509	Observe that return-code-dependent out parameter annotations are only
1510	available for retained out parameters, as non-retained object do not have to be
1511	released by the callee.
1512	These attributes are only used by the Clang Static Analyzer.
1513
1514	The family of attributes ``X_returns_X_retained`` can be added to functions,
1515	C++ methods, and Objective-C methods and properties.
1516	Attributes ``X_consumed`` can be added to parameters of methods, functions,
1517	and Objective-C methods.)reST";
1518
1519	static const char AttrDoc_CFUnknownTransfer[] = R"reST(No documentation.)reST";
1520
1521	static const char AttrDoc_CPUDispatch[] = R"reST(The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
1522	resolve multiversioned functions. This form of multiversioning provides a
1523	mechanism for declaring versions across translation units and manually
1524	specifying the resolved function list. A specified CPU defines a set of minimum
1525	features that are required for the function to be called. The result of this is
1526	that future processors execute the most restrictive version of the function the
1527	new processor can execute.
1528
1529	In addition, unlike the ICC implementation of this feature, the selection of the
1530	version does not consider the manufacturer or microarchitecture of the processor.
1531	It tests solely the list of features that are both supported by the specified
1532	processor and present in the compiler-rt library. This can be surprising at times,
1533	as the runtime processor may be from a completely different manufacturer, as long
1534	as it supports the same feature set.
1535
1536	This can additionally be surprising, as some processors are indistringuishable from
1537	others based on the list of testable features. When this happens, the variant
1538	is selected in an unspecified manner.
1539
1540	Function versions are defined with ``cpu_specific``, which takes one or more CPU
1541	names as a parameter. For example:
1542
1543	.. code-block:: c
1544
1545	// Declares and defines the ivybridge version of single_cpu.
1546	__attribute__((cpu_specific(ivybridge)))
1547	void single_cpu(void){}
1548
1549	// Declares and defines the atom version of single_cpu.
1550	__attribute__((cpu_specific(atom)))
1551	void single_cpu(void){}
1552
1553	// Declares and defines both the ivybridge and atom version of multi_cpu.
1554	__attribute__((cpu_specific(ivybridge, atom)))
1555	void multi_cpu(void){}
1556
1557	A dispatching (or resolving) function can be declared anywhere in a project's
1558	source code with ``cpu_dispatch``. This attribute takes one or more CPU names
1559	as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
1560	are not expected to be defined, only declared. If such a marked function has a
1561	definition, any side effects of the function are ignored; trivial function
1562	bodies are permissible for ICC compatibility.
1563
1564	.. code-block:: c
1565
1566	// Creates a resolver for single_cpu above.
1567	__attribute__((cpu_dispatch(ivybridge, atom)))
1568	void single_cpu(void){}
1569
1570	// Creates a resolver for multi_cpu, but adds a 3rd version defined in another
1571	// translation unit.
1572	__attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
1573	void multi_cpu(void){}
1574
1575	Note that it is possible to have a resolving function that dispatches based on
1576	more or fewer options than are present in the program. Specifying fewer will
1577	result in the omitted options not being considered during resolution. Specifying
1578	a version for resolution that isn't defined in the program will result in a
1579	linking failure.
1580
1581	It is also possible to specify a CPU name of ``generic`` which will be resolved
1582	if the executing processor doesn't satisfy the features required in the CPU
1583	name. The behavior of a program executing on a processor that doesn't satisfy
1584	any option of a multiversioned function is undefined.)reST";
1585
1586	static const char AttrDoc_CPUSpecific[] = R"reST(The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
1587	resolve multiversioned functions. This form of multiversioning provides a
1588	mechanism for declaring versions across translation units and manually
1589	specifying the resolved function list. A specified CPU defines a set of minimum
1590	features that are required for the function to be called. The result of this is
1591	that future processors execute the most restrictive version of the function the
1592	new processor can execute.
1593
1594	In addition, unlike the ICC implementation of this feature, the selection of the
1595	version does not consider the manufacturer or microarchitecture of the processor.
1596	It tests solely the list of features that are both supported by the specified
1597	processor and present in the compiler-rt library. This can be surprising at times,
1598	as the runtime processor may be from a completely different manufacturer, as long
1599	as it supports the same feature set.
1600
1601	This can additionally be surprising, as some processors are indistringuishable from
1602	others based on the list of testable features. When this happens, the variant
1603	is selected in an unspecified manner.
1604
1605	Function versions are defined with ``cpu_specific``, which takes one or more CPU
1606	names as a parameter. For example:
1607
1608	.. code-block:: c
1609
1610	// Declares and defines the ivybridge version of single_cpu.
1611	__attribute__((cpu_specific(ivybridge)))
1612	void single_cpu(void){}
1613
1614	// Declares and defines the atom version of single_cpu.
1615	__attribute__((cpu_specific(atom)))
1616	void single_cpu(void){}
1617
1618	// Declares and defines both the ivybridge and atom version of multi_cpu.
1619	__attribute__((cpu_specific(ivybridge, atom)))
1620	void multi_cpu(void){}
1621
1622	A dispatching (or resolving) function can be declared anywhere in a project's
1623	source code with ``cpu_dispatch``. This attribute takes one or more CPU names
1624	as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
1625	are not expected to be defined, only declared. If such a marked function has a
1626	definition, any side effects of the function are ignored; trivial function
1627	bodies are permissible for ICC compatibility.
1628
1629	.. code-block:: c
1630
1631	// Creates a resolver for single_cpu above.
1632	__attribute__((cpu_dispatch(ivybridge, atom)))
1633	void single_cpu(void){}
1634
1635	// Creates a resolver for multi_cpu, but adds a 3rd version defined in another
1636	// translation unit.
1637	__attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
1638	void multi_cpu(void){}
1639
1640	Note that it is possible to have a resolving function that dispatches based on
1641	more or fewer options than are present in the program. Specifying fewer will
1642	result in the omitted options not being considered during resolution. Specifying
1643	a version for resolution that isn't defined in the program will result in a
1644	linking failure.
1645
1646	It is also possible to specify a CPU name of ``generic`` which will be resolved
1647	if the executing processor doesn't satisfy the features required in the CPU
1648	name. The behavior of a program executing on a processor that doesn't satisfy
1649	any option of a multiversioned function is undefined.)reST";
1650
1651	static const char AttrDoc_CUDAClusterDims[] = R"reST(In CUDA/HIP programming, the ``cluster_dims`` attribute, conventionally exposed as the
1652	``__cluster_dims__`` macro, can be applied to a kernel function to set the dimensions of a
1653	thread block cluster, which is an optional level of hierarchy and made up of thread blocks.
1654	``__cluster_dims__`` defines the cluster size as ``(X, Y, Z)``, where each value is the number
1655	of thread blocks in that dimension. The ``cluster_dims`` and `no_cluster`` attributes are
1656	mutually exclusive.
1657
1658	.. code::
1659
1660	__global__ __cluster_dims__(2, 1, 1) void kernel(...) {
1661	...
1662	})reST";
1663
1664	static const char AttrDoc_CUDAConstant[] = R"reST(No documentation.)reST";
1665
1666	static const char AttrDoc_CUDADevice[] = R"reST(No documentation.)reST";
1667
1668	static const char AttrDoc_CUDADeviceBuiltinSurfaceType[] = R"reST(The ``device_builtin_surface_type`` attribute can be applied to a class
1669	template when declaring the surface reference. A surface reference variable
1670	could be accessed on the host side and, on the device side, might be translated
1671	into an internal surface object, which is established through surface bind and
1672	unbind runtime APIs.)reST";
1673
1674	static const char AttrDoc_CUDADeviceBuiltinTextureType[] = R"reST(The ``device_builtin_texture_type`` attribute can be applied to a class
1675	template when declaring the texture reference. A texture reference variable
1676	could be accessed on the host side and, on the device side, might be translated
1677	into an internal texture object, which is established through texture bind and
1678	unbind runtime APIs.)reST";
1679
1680	static const char AttrDoc_CUDAGlobal[] = R"reST(No documentation.)reST";
1681
1682	static const char AttrDoc_CUDAGridConstant[] = R"reST(The ``__grid_constant__`` attribute can be applied to a ``const``-qualified kernel
1683	function argument and allows compiler to take the address of that argument without
1684	making a copy. The argument applies to sm_70 or newer GPUs, during compilation
1685	with CUDA-11.7(PTX 7.7) or newer, and is ignored otherwise.)reST";
1686
1687	static const char AttrDoc_CUDAHost[] = R"reST(No documentation.)reST";
1688
1689	static const char AttrDoc_CUDAInvalidTarget[] = R"reST()reST";
1690
1691	static const char AttrDoc_CUDALaunchBounds[] = R"reST(No documentation.)reST";
1692
1693	static const char AttrDoc_CUDANoCluster[] = R"reST(In CUDA/HIP programming, a kernel function can still be launched with the cluster feature enabled
1694	at runtime, even without being annotated with ``__cluster_dims__``. The LLVM/Clang-exclusive
1695	``no_cluster`` attribute, conventionally exposed as the ``__no_cluster__`` macro, can be applied to
1696	a kernel function to explicitly indicate that the cluster feature will not be enabled either at
1697	compile time or at kernel launch time. This allows the compiler to apply certain optimizations
1698	without assuming that clustering could be enabled at runtime. It is undefined behavior to launch a
1699	kernel annotated with ``__no_cluster__`` if the cluster feature is enabled at runtime.
1700	The ``cluster_dims`` and ``no_cluster`` attributes are mutually exclusive.
1701
1702	.. code::
1703
1704	__global__ __no_cluster__ void kernel(...) {
1705	...
1706	})reST";
1707
1708	static const char AttrDoc_CUDAShared[] = R"reST(No documentation.)reST";
1709
1710	static const char AttrDoc_CXX11NoReturn[] = R"reST(A function declared as ``[[noreturn]]`` shall not return to its caller. The
1711	compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
1712	that appears to be capable of returning to its caller.
1713
1714	The ``[[_Noreturn]]`` spelling is deprecated and only exists to ease code
1715	migration for code using ``[[noreturn]]`` after including ``<stdnoreturn.h>``.)reST";
1716
1717	static const char AttrDoc_CXXAssume[] = R"reST(The ``assume`` attribute is used to indicate to the optimizer that a
1718	certain condition is assumed to be true at a certain point in the
1719	program. If this condition is violated at runtime, the behavior is
1720	undefined. ``assume`` can only be applied to a null statement.
1721
1722	Different optimisers are likely to react differently to the presence of
1723	this attribute; in some cases, adding ``assume`` may affect performance
1724	negatively. It should be used with parsimony and care.
1725
1726	Example:
1727
1728	.. code-block:: c++
1729
1730	int f(int x, int y) {
1731	[[assume(x == 27)]];
1732	[[assume(x == y)]];
1733	return y + 1; // May be optimised to `return 28`.
1734	})reST";
1735
1736	static const char AttrDoc_CallableWhen[] = R"reST(Use ``__attribute__((callable_when(...)))`` to indicate what states a method
1737	may be called in. Valid states are unconsumed, consumed, or unknown. Each
1738	argument to this attribute must be a quoted string. E.g.:
1739
1740	``__attribute__((callable_when("unconsumed", "unknown")))``)reST";
1741
1742	static const char AttrDoc_Callback[] = R"reST(The ``callback`` attribute specifies that the annotated function may invoke the
1743	specified callback zero or more times. The callback, as well as the passed
1744	arguments, are identified by their parameter name or position (starting with
1745	1!) in the annotated function. The first position in the attribute identifies
1746	the callback callee, the following positions declare describe its arguments.
1747	The callback callee is required to be callable with the number, and order, of
1748	the specified arguments. The index ``0``, or the identifier ``this``, is used to
1749	represent an implicit "this" pointer in class methods. If there is no implicit
1750	"this" pointer it shall not be referenced. The index '-1', or the name "__",
1751	represents an unknown callback callee argument. This can be a value which is
1752	not present in the declared parameter list, or one that is, but is potentially
1753	inspected, captured, or modified. Parameter names and indices can be mixed in
1754	the callback attribute.
1755
1756	The ``callback`` attribute, which is directly translated to ``callback``
1757	metadata <http://llvm.org/docs/LangRef.html#callback-metadata>, make the
1758	connection between the call to the annotated function and the callback callee.
1759	This can enable interprocedural optimizations which were otherwise impossible.
1760	If a function parameter is mentioned in the ``callback`` attribute, through its
1761	position, it is undefined if that parameter is used for anything other than the
1762	actual callback. Inspected, captured, or modified parameters shall not be
1763	listed in the ``callback`` metadata.
1764
1765	Example encodings for the callback performed by ``pthread_create`` are shown
1766	below. The explicit attribute annotation indicates that the third parameter
1767	(``start_routine``) is called zero or more times by the ``pthread_create`` function,
1768	and that the fourth parameter (``arg``) is passed along. Note that the callback
1769	behavior of ``pthread_create`` is automatically recognized by Clang. In addition,
1770	the declarations of ``__kmpc_fork_teams`` and ``__kmpc_fork_call``, generated for
1771	``#pragma omp target teams`` and ``#pragma omp parallel``, respectively, are also
1772	automatically recognized as broker functions. Further functions might be added
1773	in the future.
1774
1775	.. code-block:: c
1776
1777	__attribute__((callback (start_routine, arg)))
1778	int pthread_create(pthread_t thread, const pthread_attr_t attr,
1779	void (start_routine) (void ), void arg);
1780
1781	__attribute__((callback (3, 4)))
1782	int pthread_create(pthread_t thread, const pthread_attr_t attr,
1783	void (start_routine) (void ), void arg);)reST";
1784
1785	static const char AttrDoc_CalledOnce[] = R"reST(The ``called_once`` attribute specifies that the annotated function or method
1786	parameter is invoked exactly once on all execution paths. It only applies
1787	to parameters with function-like types, i.e. function pointers or blocks. This
1788	concept is particularly useful for asynchronous programs.
1789
1790	Clang implements a check for ``called_once`` parameters,
1791	``-Wcalled-once-parameter``. It is on by default and finds the following
1792	violations:
1793
1794	* Parameter is not called at all.
1795
1796	* Parameter is called more than once.
1797
1798	* Parameter is not called on one of the execution paths.
1799
1800	In the latter case, Clang pinpoints the path where parameter is not invoked
1801	by showing the control-flow statement where the path diverges.
1802
1803	.. code-block:: objc
1804
1805	void fooWithCallback(void (^callback)(void) __attribute__((called_once))) {
1806	if (somePredicate()) {
1807	...
1808	callback();
1809	} else {
1810	callback(); // OK: callback is called on every path
1811	}
1812	}
1813
1814	void barWithCallback(void (^callback)(void) __attribute__((called_once))) {
1815	if (somePredicate()) {
1816	...
1817	callback(); // note: previous call is here
1818	}
1819	callback(); // warning: callback is called twice
1820	}
1821
1822	void foobarWithCallback(void (^callback)(void) __attribute__((called_once))) {
1823	if (somePredicate()) { // warning: callback is not called when condition is false
1824	...
1825	callback();
1826	}
1827	}
1828
1829	This attribute is useful for API developers who want to double-check if they
1830	implemented their method correctly.)reST";
1831
1832	static const char AttrDoc_Capability[] = R"reST(No documentation.)reST";
1833
1834	static const char AttrDoc_CapturedRecord[] = R"reST()reST";
1835
1836	static const char AttrDoc_CarriesDependency[] = R"reST(The ``carries_dependency`` attribute specifies dependency propagation into and
1837	out of functions.
1838
1839	When specified on a function or Objective-C method, the ``carries_dependency``
1840	attribute means that the return value carries a dependency out of the function,
1841	so that the implementation need not constrain ordering upon return from that
1842	function. Implementations of the function and its caller may choose to preserve
1843	dependencies instead of emitting memory ordering instructions such as fences.
1844
1845	Note, this attribute does not change the meaning of the program, but may result
1846	in generation of more efficient code.)reST";
1847
1848	static const char AttrDoc_Cleanup[] = R"reST(This attribute allows a function to be run when a local variable goes out of
1849	scope. The attribute takes the identifier of a function with a parameter type
1850	that is a pointer to the type with the attribute.
1851
1852	.. code-block:: c
1853
1854	static void foo (int *) { ... }
1855	static void bar (int *) { ... }
1856	void baz (void) {
1857	int x __attribute__((cleanup(foo)));
1858	{
1859	int y __attribute__((cleanup(bar)));
1860	}
1861	}
1862
1863	The above example will result in a call to ``bar`` being passed the address of
1864	``y`` when ``y`` goes out of scope, then a call to ``foo`` being passed the
1865	address of ``x`` when ``x`` goes out of scope. If two or more variables share
1866	the same scope, their ``cleanup`` callbacks are invoked in the reverse order
1867	the variables were declared in. It is not possible to check the return value
1868	(if any) of these ``cleanup`` callback functions.)reST";
1869
1870	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).
1871
1872	.. code-block:: c
1873
1874	void __attribute__((clspv_libclc_builtin)) libclc_builtin() {}
1875
1876	.. _`clspv`: https://github.com/google/clspv
1877	.. _`libclc`: https://libclc.llvm.org)reST";
1878
1879	static const char AttrDoc_CmseNSCall[] = R"reST(This attribute declares a non-secure function type. When compiling for secure
1880	state, a call to such a function would switch from secure to non-secure state.
1881	All non-secure function calls must happen only through a function pointer, and
1882	a non-secure function type should only be used as a base type of a pointer.
1883	See `ARMv8-M Security Extensions: Requirements on Development
1884	Tools - Engineering Specification Documentation
1885	<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.)reST";
1886
1887	static const char AttrDoc_CmseNSEntry[] = R"reST(This attribute declares a function that can be called from non-secure state, or
1888	from secure state. Entering from and returning to non-secure state would switch
1889	to and from secure state, respectively, and prevent flow of information
1890	to non-secure state, except via return values. See `ARMv8-M Security Extensions:
1891	Requirements on Development Tools - Engineering Specification Documentation
1892	<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.)reST";
1893
1894	static const char AttrDoc_CodeAlign[] = R"reST(The ``clang::code_align(N)`` attribute applies to a loop and specifies the byte
1895	alignment for a loop. The attribute accepts a positive integer constant
1896	initialization expression indicating the number of bytes for the minimum
1897	alignment boundary. Its value must be a power of 2, between 1 and 4096
1898	(inclusive).
1899
1900	.. code-block:: c++
1901
1902	void foo() {
1903	int var = 0;
1904	[[clang::code_align(16)]] for (int i = 0; i < 10; ++i) var++;
1905	}
1906
1907	void Array(int *array, size_t n) {
1908	[[clang::code_align(64)]] for (int i = 0; i < n; ++i) array[i] = 0;
1909	}
1910
1911	void count () {
1912	int a1[10], int i = 0;
1913	[[clang::code_align(32)]] while (i < 10) { a1[i] += 3; }
1914	}
1915
1916	void check() {
1917	int a = 10;
1918	[[clang::code_align(8)]] do {
1919	a = a + 1;
1920	} while (a < 20);
1921	}
1922
1923	template<int A>
1924	void func() {
1925	[[clang::code_align(A)]] for(;;) { }
1926	})reST";
1927
1928	static const char AttrDoc_CodeModel[] = R"reST(The ``model`` attribute allows overriding the translation unit's
1929	code model (specified by ``-mcmodel``) for a specific global variable.
1930
1931	On LoongArch, allowed values are "normal", "medium", "extreme".
1932
1933	On x86-64, allowed values are ``"small"`` and ``"large"``. ``"small"`` is
1934	roughly equivalent to ``-mcmodel=small``, meaning the global is considered
1935	"small" placed closer to the ``.text`` section relative to "large" globals, and
1936	to prefer using 32-bit relocations to access the global. ``"large"`` is roughly
1937	equivalent to ``-mcmodel=large``, meaning the global is considered "large" and
1938	placed further from the ``.text`` section relative to "small" globals, and
1939	64-bit relocations must be used to access the global.)reST";
1940
1941	static const char AttrDoc_CodeSeg[] = R"reST(The ``__declspec(code_seg)`` attribute enables the placement of code into separate
1942	named segments that can be paged or locked in memory individually. This attribute
1943	is used to control the placement of instantiated templates and compiler-generated
1944	code. See the documentation for `__declspec(code_seg)`_ on MSDN.
1945
1946	.. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx)reST";
1947
1948	static const char AttrDoc_Cold[] = R"reST(``__attribute__((cold))`` marks a function as cold, as a manual alternative to PGO hotness data.
1949	If PGO data is available, the profile count based hotness overrides the ``__attribute__((cold))`` annotation (unlike ``__attribute__((hot))``).)reST";
1950
1951	static const char AttrDoc_Common[] = R"reST(No documentation.)reST";
1952
1953	static const char AttrDoc_Const[] = R"reST(No documentation.)reST";
1954
1955	static const char AttrDoc_ConstInit[] = R"reST(This attribute specifies that the variable to which it is attached is intended
1956	to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
1957	according to the rules of [basic.start.static]. The variable is required to
1958	have static or thread storage duration. If the initialization of the variable
1959	is not a constant initializer an error will be produced. This attribute may
1960	only be used in C++; the ``constinit`` spelling is only accepted in C++20
1961	onwards.
1962
1963	Note that in C++03 strict constant expression checking is not done. Instead
1964	the attribute reports if Clang can emit the variable as a constant, even if it's
1965	not technically a 'constant initializer'. This behavior is non-portable.
1966
1967	Static storage duration variables with constant initializers avoid hard-to-find
1968	bugs caused by the indeterminate order of dynamic initialization. They can also
1969	be safely used during dynamic initialization across translation units.
1970
1971	This attribute acts as a compile time assertion that the requirements
1972	for constant initialization have been met. Since these requirements change
1973	between dialects and have subtle pitfalls it's important to fail fast instead
1974	of silently falling back on dynamic initialization.
1975
1976	The first use of the attribute on a variable must be part of, or precede, the
1977	initializing declaration of the variable. C++20 requires the ``constinit``
1978	spelling of the attribute to be present on the initializing declaration if it
1979	is used anywhere. The other spellings can be specified on a forward declaration
1980	and omitted on a later initializing declaration.
1981
1982	.. code-block:: c++
1983
1984	// -std=c++14
1985	#define SAFE_STATIC [[clang::require_constant_initialization]]
1986	struct T {
1987	constexpr T(int) {}
1988	~T(); // non-trivial
1989	};
1990	SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
1991	SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
1992	// copy initialization is not a constant expression on a non-literal type.)reST";
1993
1994	static const char AttrDoc_Constructor[] = R"reST(The ``constructor`` attribute causes the function to be called before entering
1995	``main()``, and the ``destructor`` attribute causes the function to be called
1996	after returning from ``main()`` or when the ``exit()`` function has been
1997	called. Note, ``quick_exit()``, ``_Exit()``, and ``abort()`` prevent a function
1998	marked ``destructor`` from being called.
1999
2000	The constructor or destructor function should not accept any arguments and its
2001	return type should be ``void``.
2002
2003	The attributes accept an optional argument used to specify the priority order
2004	in which to execute constructor and destructor functions. The priority is
2005	given as an integer constant expression between 101 and 65535 (inclusive).
2006	Priorities outside of that range are reserved for use by the implementation. A
2007	lower value indicates a higher priority of initialization. Note that only the
2008	relative ordering of values is important. For example:
2009
2010	.. code-block:: c++
2011
2012	__attribute__((constructor(200))) void foo(void);
2013	__attribute__((constructor(101))) void bar(void);
2014
2015	``bar()`` will be called before ``foo()``, and both will be called before
2016	``main()``. If no argument is given to the ``constructor`` or ``destructor``
2017	attribute, they default to the value ``65535``.)reST";
2018
2019	static const char AttrDoc_Consumable[] = R"reST(Each ``class`` that uses any of the typestate annotations must first be marked
2020	using the ``consumable`` attribute. Failure to do so will result in a warning.
2021
2022	This attribute accepts a single parameter that must be one of the following:
2023	``unknown``, ``consumed``, or ``unconsumed``.)reST";
2024
2025	static const char AttrDoc_ConsumableAutoCast[] = R"reST(No documentation.)reST";
2026
2027	static const char AttrDoc_ConsumableSetOnRead[] = R"reST(No documentation.)reST";
2028
2029	static const char AttrDoc_Convergent[] = R"reST(The ``convergent`` attribute can be placed on a function declaration. It is
2030	translated into the LLVM ``convergent`` attribute, which indicates that the call
2031	instructions of a function with this attribute cannot be made control-dependent
2032	on any additional values.
2033
2034	This attribute is different from ``noduplicate`` because it allows duplicating
2035	function calls if it can be proved that the duplicated function calls are
2036	not made control-dependent on any additional values, e.g., unrolling a loop
2037	executed by all work items.
2038
2039	Sample usage:
2040
2041	.. code-block:: c
2042
2043	void convfunc(void) __attribute__((convergent));
2044	// Setting it as a C++11 attribute is also valid in a C++ program.
2045	// void convfunc(void) [[clang::convergent]];)reST";
2046
2047	static const char AttrDoc_CoroAwaitElidable[] = R"reST(The ``[[clang::coro_await_elidable]]`` is a class attribute which can be
2048	applied to a coroutine return type. It provides a hint to the compiler to apply
2049	Heap Allocation Elision more aggressively.
2050
2051	When a coroutine function returns such a type, a direct call expression therein
2052	that returns a prvalue of a type attributed ``[[clang::coro_await_elidable]]``
2053	is said to be under a safe elide context if one of the following is true:
2054	- it is the immediate right-hand side operand to a co_await expression.
2055	- it is an argument to a ``[[clang::coro_await_elidable_argument]]`` parameter
2056	or parameter pack of another direct call expression under a safe elide context.
2057
2058	Do note that the safe elide context applies only to the call expression itself,
2059	and the context does not transitively include any of its subexpressions unless
2060	exceptional rules of ``[[clang::coro_await_elidable_argument]]`` apply.
2061
2062	The compiler performs heap allocation elision on call expressions under a safe
2063	elide context, if the callee is a coroutine.
2064
2065	Example:
2066
2067	.. code-block:: c++
2068
2069	class [[clang::coro_await_elidable]] Task { ... };
2070
2071	Task foo();
2072	Task bar() {
2073	co_await foo(); // foo()'s coroutine frame on this line is elidable
2074	auto t = foo(); // foo()'s coroutine frame on this line is NOT elidable
2075	co_await t;
2076	}
2077
2078	Such elision replaces the heap allocated activation frame of the callee coroutine
2079	with a local variable within the enclosing braces in the caller's stack frame.
2080	The local variable, like other variables in coroutines, may be collected into the
2081	coroutine frame, which may be allocated on the heap. The behavior is undefined
2082	if the caller coroutine is destroyed earlier than the callee coroutine.)reST";
2083
2084	static const char AttrDoc_CoroAwaitElidableArgument[] = R"reST(The ``[[clang::coro_await_elidable_argument]]`` is a function parameter attribute.
2085	It works in conjunction with ``[[clang::coro_await_elidable]]`` to propagate a
2086	safe elide context to a parameter or parameter pack if the function is called
2087	under a safe elide context.
2088
2089	This is sometimes necessary on utility functions used to compose or modify the
2090	behavior of a callee coroutine.
2091
2092	Example:
2093
2094	.. code-block:: c++
2095
2096	template <typename T>
2097	class [[clang::coro_await_elidable]] Task { ... };
2098
2099	template <typename... T>
2100	class [[clang::coro_await_elidable]] WhenAll { ... };
2101
2102	// `when_all` is a utility function that composes coroutines. It does not
2103	// need to be a coroutine to propagate.
2104	template <typename... T>
2105	WhenAll<T...> when_all([[clang::coro_await_elidable_argument]] Task<T> tasks...);
2106
2107	Task<int> foo();
2108	Task<int> bar();
2109	Task<void> example1() {
2110	// `when_all``, `foo``, and `bar` are all elide safe because `when_all` is
2111	// under a safe elide context and, thanks to the [[clang::coro_await_elidable_argument]]
2112	// attribute, such context is propagated to foo and bar.
2113	co_await when_all(foo(), bar());
2114	}
2115
2116	Task<void> example2() {
2117	// `when_all` and `bar` are elide safe. `foo` is not elide safe.
2118	auto f = foo();
2119	co_await when_all(f, bar());
2120	}
2121
2122
2123	Task<void> example3() {
2124	// None of the calls are elide safe.
2125	auto t = when_all(foo(), bar());
2126	co_await t;
2127	})reST";
2128
2129	static const char AttrDoc_CoroDisableLifetimeBound[] = R"reST(The ``[[clang::coro_lifetimebound]]`` is a class attribute which can be applied
2130	to a coroutine return type (`coro_return_type, coro_wrapper`_) (i.e.
2131	it should also be annotated with ``[[clang::coro_return_type]]``).
2132
2133	All parameters of a function are considered to be lifetime bound if the function returns a
2134	coroutine return type (CRT) annotated with ``[[clang::coro_lifetimebound]]``.
2135	This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the function
2136	with ``[[clang::coro_disable_lifetimebound]]`` function attribute .
2137	See documentation of `lifetimebound`_ for details about lifetime bound analysis.
2138
2139
2140	Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.
2141
2142	For example,
2143
2144	.. code-block:: c++
2145
2146	task<int> coro(const int& a) { co_return a + 1; }
2147	task<int> dangling_refs(int a) {
2148	// `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.
2149	auto foo = coro(1);
2150	// `coro` captures reference to local variable `a` which is destroyed after the return.
2151	return coro(a);
2152	}
2153
2154	Lifetime bound static analysis can be used to detect such instances when coroutines capture references
2155	which may die earlier than the coroutine frame itself. In the above example, if the CRT `task` is annotated with
2156	``[[clang::coro_lifetimebound]]``, then lifetime bound analysis would detect capturing reference to
2157	temporaries or return address of a local variable.
2158
2159	Both coroutines and coroutine wrappers are part of this analysis.
2160
2161	.. code-block:: c++
2162
2163	template <typename T> struct [[clang::coro_return_type, clang::coro_lifetimebound]] Task {
2164	using promise_type = some_promise_type;
2165	};
2166
2167	Task<int> coro(const int& a) { co_return a + 1; }
2168	[[clang::coro_wrapper]] Task<int> coro_wrapper(const int& a, const int& b) {
2169	return a > b ? coro(a) : coro(b);
2170	}
2171	Task<int> temporary_reference() {
2172	auto foo = coro(1); // warning: capturing reference to a temporary which would die after the expression.
2173
2174	int a = 1;
2175	auto bar = coro_wrapper(a, 0); // warning: `b` captures reference to a temporary.
2176
2177	co_return co_await coro(1); // fine.
2178	}
2179	[[clang::coro_wrapper]] Task<int> stack_reference(int a) {
2180	return coro(a); // warning: returning address of stack variable `a`.
2181	}
2182
2183	This analysis can be disabled for all calls to a particular function by annotating the function
2184	with function attribute ``[[clang::coro_disable_lifetimebound]]``.
2185	For example, this could be useful for coroutine wrappers which accept reference parameters
2186	but do not pass them to the underlying coroutine or pass them by value.
2187
2188	.. code-block:: c++
2189
2190	Task<int> coro(int a) { co_return a + 1; }
2191	[[clang::coro_wrapper, clang::coro_disable_lifetimebound]] Task<int> coro_wrapper(const int& a) {
2192	return coro(a + 1);
2193	}
2194	void use() {
2195	auto task = coro_wrapper(1); // use of temporary is fine as the argument is not lifetime bound.
2196	})reST";
2197
2198	static const char AttrDoc_CoroLifetimeBound[] = R"reST(The ``[[clang::coro_lifetimebound]]`` is a class attribute which can be applied
2199	to a coroutine return type (`coro_return_type, coro_wrapper`_) (i.e.
2200	it should also be annotated with ``[[clang::coro_return_type]]``).
2201
2202	All parameters of a function are considered to be lifetime bound if the function returns a
2203	coroutine return type (CRT) annotated with ``[[clang::coro_lifetimebound]]``.
2204	This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the function
2205	with ``[[clang::coro_disable_lifetimebound]]`` function attribute .
2206	See documentation of `lifetimebound`_ for details about lifetime bound analysis.
2207
2208
2209	Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.
2210
2211	For example,
2212
2213	.. code-block:: c++
2214
2215	task<int> coro(const int& a) { co_return a + 1; }
2216	task<int> dangling_refs(int a) {
2217	// `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.
2218	auto foo = coro(1);
2219	// `coro` captures reference to local variable `a` which is destroyed after the return.
2220	return coro(a);
2221	}
2222
2223	Lifetime bound static analysis can be used to detect such instances when coroutines capture references
2224	which may die earlier than the coroutine frame itself. In the above example, if the CRT `task` is annotated with
2225	``[[clang::coro_lifetimebound]]``, then lifetime bound analysis would detect capturing reference to
2226	temporaries or return address of a local variable.
2227
2228	Both coroutines and coroutine wrappers are part of this analysis.
2229
2230	.. code-block:: c++
2231
2232	template <typename T> struct [[clang::coro_return_type, clang::coro_lifetimebound]] Task {
2233	using promise_type = some_promise_type;
2234	};
2235
2236	Task<int> coro(const int& a) { co_return a + 1; }
2237	[[clang::coro_wrapper]] Task<int> coro_wrapper(const int& a, const int& b) {
2238	return a > b ? coro(a) : coro(b);
2239	}
2240	Task<int> temporary_reference() {
2241	auto foo = coro(1); // warning: capturing reference to a temporary which would die after the expression.
2242
2243	int a = 1;
2244	auto bar = coro_wrapper(a, 0); // warning: `b` captures reference to a temporary.
2245
2246	co_return co_await coro(1); // fine.
2247	}
2248	[[clang::coro_wrapper]] Task<int> stack_reference(int a) {
2249	return coro(a); // warning: returning address of stack variable `a`.
2250	}
2251
2252	This analysis can be disabled for all calls to a particular function by annotating the function
2253	with function attribute ``[[clang::coro_disable_lifetimebound]]``.
2254	For example, this could be useful for coroutine wrappers which accept reference parameters
2255	but do not pass them to the underlying coroutine or pass them by value.
2256
2257	.. code-block:: c++
2258
2259	Task<int> coro(int a) { co_return a + 1; }
2260	[[clang::coro_wrapper, clang::coro_disable_lifetimebound]] Task<int> coro_wrapper(const int& a) {
2261	return coro(a + 1);
2262	}
2263	void use() {
2264	auto task = coro_wrapper(1); // use of temporary is fine as the argument is not lifetime bound.
2265	})reST";
2266
2267	static const char AttrDoc_CoroOnlyDestroyWhenComplete[] = R"reST(The `coro_only_destroy_when_complete` attribute should be marked on a C++ class. The coroutines
2268	whose return type is marked with the attribute are assumed to be destroyed only after the coroutine has
2269	reached the final suspend point.
2270
2271	This is helpful for the optimizers to reduce the size of the destroy function for the coroutines.
2272
2273	For example,
2274
2275	.. code-block:: c++
2276
2277	A foo() {
2278	dtor d;
2279	co_await something();
2280	dtor d1;
2281	co_await something();
2282	dtor d2;
2283	co_return 43;
2284	}
2285
2286	The compiler may generate the following pseudocode:
2287
2288	.. code-block:: c++
2289
2290	void foo.destroy(foo.Frame *frame) {
2291	switch(frame->suspend_index()) {
2292	case 1:
2293	frame->d.~dtor();
2294	break;
2295	case 2:
2296	frame->d.~dtor();
2297	frame->d1.~dtor();
2298	break;
2299	case 3:
2300	frame->d.~dtor();
2301	frame->d1.~dtor();
2302	frame->d2.~dtor();
2303	break;
2304	default: // coroutine completed or haven't started
2305	break;
2306	}
2307
2308	frame->promise.~promise_type();
2309	delete frame;
2310	}
2311
2312	The `foo.destroy()` function's purpose is to release all of the resources
2313	initialized for the coroutine when it is destroyed in a suspended state.
2314	However, if the coroutine is only ever destroyed at the final suspend state,
2315	the rest of the conditions are superfluous.
2316
2317	The user can use the `coro_only_destroy_when_complete` attributo suppress
2318	generation of the other destruction cases, optimizing the above `foo.destroy` to:
2319
2320	.. code-block:: c++
2321
2322	void foo.destroy(foo.Frame *frame) {
2323	frame->promise.~promise_type();
2324	delete frame;
2325	})reST";
2326
2327	static const char AttrDoc_CoroReturnType[] = R"reST(The ``[[clang::coro_return_type]]`` attribute is used to help static analyzers to recognize
2328	coroutines from the function signatures.
2329
2330	The ``coro_return_type`` attribute should be marked on a C++ class to mark it as
2331	a coroutine return type (CRT).
2332
2333	A function ``R func(P1, .., PN)`` has a coroutine return type (CRT) ``R`` if ``R``
2334	is marked by ``[[clang::coro_return_type]]`` and ``R`` has a promise type associated to it
2335	(i.e., std::coroutine_traits<R, P1, .., PN>::promise_type is a valid promise type).
2336
2337	If the return type of a function is a ``CRT`` then the function must be a coroutine.
2338	Otherwise the program is invalid. It is allowed for a non-coroutine to return a ``CRT``
2339	if the function is marked with ``[[clang::coro_wrapper]]``.
2340
2341	The ``[[clang::coro_wrapper]]`` attribute should be marked on a C++ function to mark it as
2342	a coroutine wrapper. A coroutine wrapper is a function which returns a ``CRT``,
2343	is not a coroutine itself and is marked with ``[[clang::coro_wrapper]]``.
2344
2345	Clang will enforce that all functions that return a ``CRT`` are either coroutines or marked
2346	with ``[[clang::coro_wrapper]]``. Clang will enforce this with an error.
2347
2348	From a language perspective, it is not possible to differentiate between a coroutine and a
2349	function returning a CRT by merely looking at the function signature.
2350
2351	Coroutine wrappers, in particular, are susceptible to capturing
2352	references to temporaries and other lifetime issues. This allows to avoid such lifetime
2353	issues with coroutine wrappers.
2354
2355	For example,
2356
2357	.. code-block:: c++
2358
2359	// This is a CRT.
2360	template <typename T> struct [[clang::coro_return_type]] Task {
2361	using promise_type = some_promise_type;
2362	};
2363
2364	Task<int> increment(int a) { co_return a + 1; } // Fine. This is a coroutine.
2365	Task<int> foo() { return increment(1); } // Error. foo is not a coroutine.
2366
2367	// Fine for a coroutine wrapper to return a CRT.
2368	[[clang::coro_wrapper]] Task<int> foo() { return increment(1); }
2369
2370	void bar() {
2371	// Invalid. This intantiates a function which returns a CRT but is not marked as
2372	// a coroutine wrapper.
2373	std::function<Task<int>(int)> f = increment;
2374	}
2375
2376	Note: ``a_promise_type::get_return_object`` is exempted from this analysis as it is a necessary
2377	implementation detail of any coroutine library.)reST";
2378
2379	static const char AttrDoc_CoroWrapper[] = R"reST(The ``[[clang::coro_return_type]]`` attribute is used to help static analyzers to recognize
2380	coroutines from the function signatures.
2381
2382	The ``coro_return_type`` attribute should be marked on a C++ class to mark it as
2383	a coroutine return type (CRT).
2384
2385	A function ``R func(P1, .., PN)`` has a coroutine return type (CRT) ``R`` if ``R``
2386	is marked by ``[[clang::coro_return_type]]`` and ``R`` has a promise type associated to it
2387	(i.e., std::coroutine_traits<R, P1, .., PN>::promise_type is a valid promise type).
2388
2389	If the return type of a function is a ``CRT`` then the function must be a coroutine.
2390	Otherwise the program is invalid. It is allowed for a non-coroutine to return a ``CRT``
2391	if the function is marked with ``[[clang::coro_wrapper]]``.
2392
2393	The ``[[clang::coro_wrapper]]`` attribute should be marked on a C++ function to mark it as
2394	a coroutine wrapper. A coroutine wrapper is a function which returns a ``CRT``,
2395	is not a coroutine itself and is marked with ``[[clang::coro_wrapper]]``.
2396
2397	Clang will enforce that all functions that return a ``CRT`` are either coroutines or marked
2398	with ``[[clang::coro_wrapper]]``. Clang will enforce this with an error.
2399
2400	From a language perspective, it is not possible to differentiate between a coroutine and a
2401	function returning a CRT by merely looking at the function signature.
2402
2403	Coroutine wrappers, in particular, are susceptible to capturing
2404	references to temporaries and other lifetime issues. This allows to avoid such lifetime
2405	issues with coroutine wrappers.
2406
2407	For example,
2408
2409	.. code-block:: c++
2410
2411	// This is a CRT.
2412	template <typename T> struct [[clang::coro_return_type]] Task {
2413	using promise_type = some_promise_type;
2414	};
2415
2416	Task<int> increment(int a) { co_return a + 1; } // Fine. This is a coroutine.
2417	Task<int> foo() { return increment(1); } // Error. foo is not a coroutine.
2418
2419	// Fine for a coroutine wrapper to return a CRT.
2420	[[clang::coro_wrapper]] Task<int> foo() { return increment(1); }
2421
2422	void bar() {
2423	// Invalid. This intantiates a function which returns a CRT but is not marked as
2424	// a coroutine wrapper.
2425	std::function<Task<int>(int)> f = increment;
2426	}
2427
2428	Note: ``a_promise_type::get_return_object`` is exempted from this analysis as it is a necessary
2429	implementation detail of any coroutine library.)reST";
2430
2431	static const char AttrDoc_CountedBy[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
2432	structure in C. The argument for the attribute is the name of a field member
2433	holding the count of elements in the flexible array. This information can be
2434	used to improve the results of the array bound sanitizer and the
2435	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
2436	within the same non-anonymous, enclosing struct as the flexible array member.
2437
2438	This example specifies that the flexible array member ``array`` has the number
2439	of elements allocated for it in ``count``:
2440
2441	.. code-block:: c
2442
2443	struct bar;
2444
2445	struct foo {
2446	size_t count;
2447	char other;
2448	struct bar *array[] __attribute__((counted_by(count)));
2449	};
2450
2451	This establishes a relationship between ``array`` and ``count``. Specifically,
2452	``array`` must have at least ``count`` number of elements available. It's the
2453	user's responsibility to ensure that this relationship is maintained through
2454	changes to the structure.
2455
2456	In the following example, the allocated array erroneously has fewer elements
2457	than what's specified by ``p->count``. This would result in an out-of-bounds
2458	access not being detected.
2459
2460	.. code-block:: c
2461
2462	#define SIZE_INCR 42
2463
2464	struct foo *p;
2465
2466	void foo_alloc(size_t count) {
2467	p = malloc(MAX(sizeof(struct foo),
2468	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2469	p->count = count + SIZE_INCR;
2470	}
2471
2472	The next example updates ``p->count``, but breaks the relationship requirement
2473	that ``p->array`` must have at least ``p->count`` number of elements available:
2474
2475	.. code-block:: c
2476
2477	#define SIZE_INCR 42
2478
2479	struct foo *p;
2480
2481	void foo_alloc(size_t count) {
2482	p = malloc(MAX(sizeof(struct foo),
2483	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2484	p->count = count;
2485	}
2486
2487	void use_foo(int index, int val) {
2488	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
2489	p->array[index] = val; /* The sanitizer can't properly check this access. */
2490	}
2491
2492	In this example, an update to ``p->count`` maintains the relationship
2493	requirement:
2494
2495	.. code-block:: c
2496
2497	void use_foo(int index, int val) {
2498	if (p->count == 0)
2499	return;
2500	--p->count;
2501	p->array[index] = val;
2502	})reST";
2503
2504	static const char AttrDoc_CountedByOrNull[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
2505	structure in C. The argument for the attribute is the name of a field member
2506	holding the count of elements in the flexible array. This information can be
2507	used to improve the results of the array bound sanitizer and the
2508	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
2509	within the same non-anonymous, enclosing struct as the flexible array member.
2510
2511	This example specifies that the flexible array member ``array`` has the number
2512	of elements allocated for it in ``count``:
2513
2514	.. code-block:: c
2515
2516	struct bar;
2517
2518	struct foo {
2519	size_t count;
2520	char other;
2521	struct bar *array[] __attribute__((counted_by(count)));
2522	};
2523
2524	This establishes a relationship between ``array`` and ``count``. Specifically,
2525	``array`` must have at least ``count`` number of elements available. It's the
2526	user's responsibility to ensure that this relationship is maintained through
2527	changes to the structure.
2528
2529	In the following example, the allocated array erroneously has fewer elements
2530	than what's specified by ``p->count``. This would result in an out-of-bounds
2531	access not being detected.
2532
2533	.. code-block:: c
2534
2535	#define SIZE_INCR 42
2536
2537	struct foo *p;
2538
2539	void foo_alloc(size_t count) {
2540	p = malloc(MAX(sizeof(struct foo),
2541	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2542	p->count = count + SIZE_INCR;
2543	}
2544
2545	The next example updates ``p->count``, but breaks the relationship requirement
2546	that ``p->array`` must have at least ``p->count`` number of elements available:
2547
2548	.. code-block:: c
2549
2550	#define SIZE_INCR 42
2551
2552	struct foo *p;
2553
2554	void foo_alloc(size_t count) {
2555	p = malloc(MAX(sizeof(struct foo),
2556	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
2557	p->count = count;
2558	}
2559
2560	void use_foo(int index, int val) {
2561	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
2562	p->array[index] = val; /* The sanitizer can't properly check this access. */
2563	}
2564
2565	In this example, an update to ``p->count`` maintains the relationship
2566	requirement:
2567
2568	.. code-block:: c
2569
2570	void use_foo(int index, int val) {
2571	if (p->count == 0)
2572	return;
2573	--p->count;
2574	p->array[index] = val;
2575	})reST";
2576
2577	static const char AttrDoc_DLLExport[] = R"reST(The ``__declspec(dllexport)`` attribute declares a variable, function, or
2578	Objective-C interface to be exported from the module. It is available under the
2579	``-fdeclspec`` flag for compatibility with various compilers. The primary use
2580	is for COFF object files which explicitly specify what interfaces are available
2581	for external use. See the dllexport_ documentation on MSDN for more
2582	information.
2583
2584	.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx)reST";
2585
2586	static const char AttrDoc_DLLExportOnDecl[] = R"reST()reST";
2587
2588	static const char AttrDoc_DLLExportStaticLocal[] = R"reST()reST";
2589
2590	static const char AttrDoc_DLLImport[] = R"reST(The ``__declspec(dllimport)`` attribute declares a variable, function, or
2591	Objective-C interface to be imported from an external module. It is available
2592	under the ``-fdeclspec`` flag for compatibility with various compilers. The
2593	primary use is for COFF object files which explicitly specify what interfaces
2594	are imported from external modules. See the dllimport_ documentation on MSDN
2595	for more information.
2596
2597	Note that a dllimport function may still be inlined, if its definition is
2598	available and it doesn't reference any non-dllimport functions or global
2599	variables.
2600
2601	.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx)reST";
2602
2603	static const char AttrDoc_DLLImportStaticLocal[] = R"reST()reST";
2604
2605	static const char AttrDoc_Deprecated[] = R"reST(The ``deprecated`` attribute can be applied to a function, a variable, or a
2606	type. This is useful when identifying functions, variables, or types that are
2607	expected to be removed in a future version of a program.
2608
2609	Consider the function declaration for a hypothetical function ``f``:
2610
2611	.. code-block:: c++
2612
2613	void f(void) __attribute__((deprecated("message", "replacement")));
2614
2615	When spelled as ``__attribute__((deprecated))``, the deprecated attribute can have
2616	two optional string arguments. The first one is the message to display when
2617	emitting the warning; the second one enables the compiler to provide a Fix-It
2618	to replace the deprecated name with a new name. Otherwise, when spelled as
2619	``[[gnu::deprecated]]`` or ``[[deprecated]]``, the attribute can have one optional
2620	string argument which is the message to display when emitting the warning.)reST";
2621
2622	static const char AttrDoc_Destructor[] = R"reST(The ``constructor`` attribute causes the function to be called before entering
2623	``main()``, and the ``destructor`` attribute causes the function to be called
2624	after returning from ``main()`` or when the ``exit()`` function has been
2625	called. Note, ``quick_exit()``, ``_Exit()``, and ``abort()`` prevent a function
2626	marked ``destructor`` from being called.
2627
2628	The constructor or destructor function should not accept any arguments and its
2629	return type should be ``void``.
2630
2631	The attributes accept an optional argument used to specify the priority order
2632	in which to execute constructor and destructor functions. The priority is
2633	given as an integer constant expression between 101 and 65535 (inclusive).
2634	Priorities outside of that range are reserved for use by the implementation. A
2635	lower value indicates a higher priority of initialization. Note that only the
2636	relative ordering of values is important. For example:
2637
2638	.. code-block:: c++
2639
2640	__attribute__((constructor(200))) void foo(void);
2641	__attribute__((constructor(101))) void bar(void);
2642
2643	``bar()`` will be called before ``foo()``, and both will be called before
2644	``main()``. If no argument is given to the ``constructor`` or ``destructor``
2645	attribute, they default to the value ``65535``.)reST";
2646
2647	static const char AttrDoc_DeviceKernel[] = R"reST(These attributes specify that the function represents a kernel for device offloading.
2648	The specific semantics depend on the offloading language, target, and attribute spelling.
2649	Here is a code example using the attribute to mark a function as a kernel:
2650
2651	.. code-block:: c++
2652
2653	[[clang::device_kernel]] int foo(int x) { return ++x; })reST";
2654
2655	static const char AttrDoc_DiagnoseAsBuiltin[] = R"reST(The ``diagnose_as_builtin`` attribute indicates that Fortify diagnostics are to
2656	be applied to the declared function as if it were the function specified by the
2657	attribute. The builtin function whose diagnostics are to be mimicked should be
2658	given. In addition, the order in which arguments should be applied must also
2659	be given.
2660
2661	For example, the attribute can be used as follows.
2662
2663	.. code-block:: c
2664
2665	__attribute__((diagnose_as_builtin(__builtin_memset, 3, 2, 1)))
2666	void mymemset(int n, int c, void s) {
2667	// ...
2668	}
2669
2670	This indicates that calls to ``mymemset`` should be diagnosed as if they were
2671	calls to ``__builtin_memset``. The arguments ``3, 2, 1`` indicate by index the
2672	order in which arguments of ``mymemset`` should be applied to
2673	``__builtin_memset``. The third argument should be applied first, then the
2674	second, and then the first. Thus (when Fortify warnings are enabled) the call
2675	``mymemset(n, c, s)`` will diagnose overflows as if it were the call
2676	``__builtin_memset(s, c, n)``.
2677
2678	For variadic functions, the variadic arguments must come in the same order as
2679	they would to the builtin function, after all normal arguments. For instance,
2680	to diagnose a new function as if it were `sscanf`, we can use the attribute as
2681	follows.
2682
2683	.. code-block:: c
2684
2685	__attribute__((diagnose_as_builtin(sscanf, 1, 2)))
2686	int mysscanf(const char str, const char format, ...) {
2687	// ...
2688	}
2689
2690	Then the call `mysscanf("abc def", "%4s %4s", buf1, buf2)` will be diagnosed as
2691	if it were the call `sscanf("abc def", "%4s %4s", buf1, buf2)`.
2692
2693	This attribute cannot be applied to non-static member functions.)reST";
2694
2695	static const char AttrDoc_DiagnoseIf[] = R"reST(The ``diagnose_if`` attribute can be placed on function declarations to emit
2696	warnings or errors at compile-time if calls to the attributed function meet
2697	certain user-defined criteria. For example:
2698
2699	.. code-block:: c
2700
2701	int abs(int a)
2702	__attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
2703	int must_abs(int a)
2704	__attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
2705
2706	int val = abs(1); // warning: Redundant abs call
2707	int val2 = must_abs(1); // error: Redundant abs call
2708	int val3 = abs(val);
2709	int val4 = must_abs(val); // Because run-time checks are not emitted for
2710	// diagnose_if attributes, this executes without
2711	// issue.
2712
2713
2714	``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
2715
2716	* Overload resolution is not aware of ``diagnose_if`` attributes: they're
2717	considered only after we select the best candidate from a given candidate set.
2718	* Function declarations that differ only in their ``diagnose_if`` attributes are
2719	considered to be redeclarations of the same function (not overloads).
2720	* If the condition provided to ``diagnose_if`` cannot be evaluated, no
2721	diagnostic will be emitted.
2722
2723	Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
2724
2725	As a result of bullet number two, ``diagnose_if`` attributes will stack on the
2726	same function. For example:
2727
2728	.. code-block:: c
2729
2730	int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
2731	int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
2732
2733	int bar = foo(); // warning: diag1
2734	// warning: diag2
2735	int (*fooptr)(void) = foo; // warning: diag1
2736	// warning: diag2
2737
2738	constexpr int supportsAPILevel(int N) { return N < 5; }
2739	int baz(int a)
2740	__attribute__((diagnose_if(!supportsAPILevel(10),
2741	"Upgrade to API level 10 to use baz", "error")));
2742	int baz(int a)
2743	__attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
2744
2745	int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
2746	int v = baz(0); // error: Upgrade to API level 10 to use baz
2747
2748	Query for this feature with ``__has_attribute(diagnose_if)``.)reST";
2749
2750	static const char AttrDoc_DisableSanitizerInstrumentation[] = R"reST(Use the ``disable_sanitizer_instrumentation`` attribute on a function,
2751	Objective-C method, or global variable, to specify that no sanitizer
2752	instrumentation should be applied.
2753
2754	This is not the same as ``__attribute__((no_sanitize(...)))``, which depending
2755	on the tool may still insert instrumentation to prevent false positive reports.)reST";
2756
2757	static const char AttrDoc_DisableTailCalls[] = R"reST(The ``disable_tail_calls`` attribute instructs the backend to not perform tail
2758	call optimization inside the marked function.
2759
2760	For example:
2761
2762	.. code-block:: c
2763
2764	int callee(int);
2765
2766	int foo(int a) __attribute__((disable_tail_calls)) {
2767	return callee(a); // This call is not tail-call optimized.
2768	}
2769
2770	Marking virtual functions as ``disable_tail_calls`` is legal.
2771
2772	.. code-block:: c++
2773
2774	int callee(int);
2775
2776	class Base {
2777	public:
2778	[[clang::disable_tail_calls]] virtual int foo1() {
2779	return callee(); // This call is not tail-call optimized.
2780	}
2781	};
2782
2783	class Derived1 : public Base {
2784	public:
2785	int foo1() override {
2786	return callee(); // This call is tail-call optimized.
2787	}
2788	};)reST";
2789
2790	static const char AttrDoc_EmptyBases[] = R"reST(The empty_bases attribute permits the compiler to utilize the
2791	empty-base-optimization more frequently.
2792	This attribute only applies to struct, class, and union types.
2793	It is only supported when using the Microsoft C++ ABI.)reST";
2794
2795	static const char AttrDoc_EnableIf[] = R"reST(.. Note:: Some features of this attribute are experimental. The meaning of
2796	multiple enable_if attributes on a single declaration is subject to change in
2797	a future version of clang. Also, the ABI is not standardized and the name
2798	mangling may change in future versions. To avoid that, use asm labels.
2799
2800	The ``enable_if`` attribute can be placed on function declarations to control
2801	which overload is selected based on the values of the function's arguments.
2802	When combined with the ``overloadable`` attribute, this feature is also
2803	available in C.
2804
2805	.. code-block:: c++
2806
2807	int isdigit(int c);
2808	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")));
2809
2810	void foo(char c) {
2811	isdigit(c);
2812	isdigit(10);
2813	isdigit(-10); // results in a compile-time error.
2814	}
2815
2816	The enable_if attribute takes two arguments, the first is an expression written
2817	in terms of the function parameters, the second is a string explaining why this
2818	overload candidate could not be selected to be displayed in diagnostics. The
2819	expression is part of the function signature for the purposes of determining
2820	whether it is a redeclaration (following the rules used when determining
2821	whether a C++ template specialization is ODR-equivalent), but is not part of
2822	the type.
2823
2824	The enable_if expression is evaluated as if it were the body of a
2825	bool-returning constexpr function declared with the arguments of the function
2826	it is being applied to, then called with the parameters at the call site. If the
2827	result is false or could not be determined through constant expression
2828	evaluation, then this overload will not be chosen and the provided string may
2829	be used in a diagnostic if the compile fails as a result.
2830
2831	Because the enable_if expression is an unevaluated context, there are no global
2832	state changes, nor the ability to pass information from the enable_if
2833	expression to the function body. For example, suppose we want calls to
2834	strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
2835	strbuf) only if the size of strbuf can be determined:
2836
2837	.. code-block:: c++
2838
2839	__attribute__((always_inline))
2840	static inline size_t strnlen(const char *s, size_t maxlen)
2841	__attribute__((overloadable))
2842	__attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
2843	"chosen when the buffer size is known but 'maxlen' is not")))
2844	{
2845	return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
2846	}
2847
2848	Multiple enable_if attributes may be applied to a single declaration. In this
2849	case, the enable_if expressions are evaluated from left to right in the
2850	following manner. First, the candidates whose enable_if expressions evaluate to
2851	false or cannot be evaluated are discarded. If the remaining candidates do not
2852	share ODR-equivalent enable_if expressions, the overload resolution is
2853	ambiguous. Otherwise, enable_if overload resolution continues with the next
2854	enable_if attribute on the candidates that have not been discarded and have
2855	remaining enable_if attributes. In this way, we pick the most specific
2856	overload out of a number of viable overloads using enable_if.
2857
2858	.. code-block:: c++
2859
2860	void f() __attribute__((enable_if(true, ""))); // #1
2861	void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
2862
2863	void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
2864	void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
2865
2866	In this example, a call to f() is always resolved to #2, as the first enable_if
2867	expression is ODR-equivalent for both declarations, but #1 does not have another
2868	enable_if expression to continue evaluating, so the next round of evaluation has
2869	only a single candidate. In a call to g(1, 1), the call is ambiguous even though
2870	#2 has more enable_if attributes, because the first enable_if expressions are
2871	not ODR-equivalent.
2872
2873	Query for this feature with ``__has_attribute(enable_if)``.
2874
2875	Note that functions with one or more ``enable_if`` attributes may not have
2876	their address taken, unless all of the conditions specified by said
2877	``enable_if`` are constants that evaluate to ``true``. For example:
2878
2879	.. code-block:: c
2880
2881	const int TrueConstant = 1;
2882	const int FalseConstant = 0;
2883	int f(int a) __attribute__((enable_if(a > 0, "")));
2884	int g(int a) __attribute__((enable_if(a == 0 \|\| a != 0, "")));
2885	int h(int a) __attribute__((enable_if(1, "")));
2886	int i(int a) __attribute__((enable_if(TrueConstant, "")));
2887	int j(int a) __attribute__((enable_if(FalseConstant, "")));
2888
2889	void fn() {
2890	int (*ptr)(int);
2891	ptr = &f; // error: 'a > 0' is not always true
2892	ptr = &g; // error: 'a == 0 \|\| a != 0' is not a truthy constant
2893	ptr = &h; // OK: 1 is a truthy constant
2894	ptr = &i; // OK: 'TrueConstant' is a truthy constant
2895	ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
2896	}
2897
2898	Because ``enable_if`` evaluation happens during overload resolution,
2899	``enable_if`` may give unintuitive results when used with templates, depending
2900	on when overloads are resolved. In the example below, clang will emit a
2901	diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``:
2902
2903	.. code-block:: c++
2904
2905	double foo(int i) __attribute__((enable_if(i > 0, "")));
2906	void *foo(int i) __attribute__((enable_if(i <= 0, "")));
2907	template <int I>
2908	auto bar() { return foo(I); }
2909
2910	template <typename T>
2911	auto baz() { return foo(T::number); }
2912
2913	struct WithNumber { constexpr static int number = 1; };
2914	void callThem() {
2915	bar<sizeof(WithNumber)>();
2916	baz<WithNumber>();
2917	}
2918
2919	This is because, in ``bar``, ``foo`` is resolved prior to template
2920	instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
2921	conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
2922	template instantiation, so the value for ``T::number`` is known.)reST";
2923
2924	static const char AttrDoc_EnforceTCB[] = R"reST(The ``enforce_tcb`` attribute can be placed on functions to enforce that a
2925	trusted compute base (TCB) does not call out of the TCB. This generates a
2926	warning every time a function not marked with an ``enforce_tcb`` attribute is
2927	called from a function with the ``enforce_tcb`` attribute. A function may be a
2928	part of multiple TCBs. Invocations through function pointers are currently
2929	not checked. Builtins are considered to a part of every TCB.
2930
2931	- ``enforce_tcb(Name)`` indicates that this function is a part of the TCB named ``Name``)reST";
2932
2933	static const char AttrDoc_EnforceTCBLeaf[] = R"reST(The ``enforce_tcb_leaf`` attribute satisfies the requirement enforced by
2934	``enforce_tcb`` for the marked function to be in the named TCB but does not
2935	continue to check the functions called from within the leaf function.
2936
2937	- ``enforce_tcb_leaf(Name)`` indicates that this function is a part of the TCB named ``Name``)reST";
2938
2939	static const char AttrDoc_EnumExtensibility[] = R"reST(Attribute ``enum_extensibility`` is used to distinguish between enum definitions
2940	that are extensible and those that are not. The attribute can take either
2941	``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
2942	enum type takes a value that corresponds to one of the enumerators listed in the
2943	enum definition or, when the enum is annotated with ``flag_enum``, a value that
2944	can be constructed using values corresponding to the enumerators. ``open``
2945	indicates a variable of the enum type can take any values allowed by the
2946	standard and instructs clang to be more lenient when issuing warnings.
2947
2948	.. code-block:: c
2949
2950	enum __attribute__((enum_extensibility(closed))) ClosedEnum {
2951	A0, A1
2952	};
2953
2954	enum __attribute__((enum_extensibility(open))) OpenEnum {
2955	B0, B1
2956	};
2957
2958	enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
2959	C0 = 1 << 0, C1 = 1 << 1
2960	};
2961
2962	enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
2963	D0 = 1 << 0, D1 = 1 << 1
2964	};
2965
2966	void foo1() {
2967	enum ClosedEnum ce;
2968	enum OpenEnum oe;
2969	enum ClosedFlagEnum cfe;
2970	enum OpenFlagEnum ofe;
2971
2972	ce = A1; // no warnings
2973	ce = 100; // warning issued
2974	oe = B1; // no warnings
2975	oe = 100; // no warnings
2976	cfe = C0 \| C1; // no warnings
2977	cfe = C0 \| C1 \| 4; // warning issued
2978	ofe = D0 \| D1; // no warnings
2979	ofe = D0 \| D1 \| 4; // no warnings
2980	})reST";
2981
2982	static const char AttrDoc_Error[] = R"reST(The ``error`` and ``warning`` function attributes can be used to specify a
2983	custom diagnostic to be emitted when a call to such a function is not
2984	eliminated via optimizations. This can be used to create compile time
2985	assertions that depend on optimizations, while providing diagnostics
2986	pointing to precise locations of the call site in the source.
2987
2988	.. code-block:: c++
2989
2990	__attribute__((warning("oh no"))) void dontcall();
2991	void foo() {
2992	if (someCompileTimeAssertionThatsTrue)
2993	dontcall(); // Warning
2994
2995	dontcall(); // Warning
2996
2997	if (someCompileTimeAssertionThatsFalse)
2998	dontcall(); // No Warning
2999	sizeof(dontcall()); // No Warning
3000	})reST";
3001
3002	static const char AttrDoc_ExcludeFromExplicitInstantiation[] = R"reST(The ``exclude_from_explicit_instantiation`` attribute opts-out a member of a
3003	class template from being part of explicit template instantiations of that
3004	class template. This means that an explicit instantiation will not instantiate
3005	members of the class template marked with the attribute, but also that code
3006	where an extern template declaration of the enclosing class template is visible
3007	will not take for granted that an external instantiation of the class template
3008	would provide those members (which would otherwise be a link error, since the
3009	explicit instantiation won't provide those members). For example, let's say we
3010	don't want the ``data()`` method to be part of libc++'s ABI. To make sure it
3011	is not exported from the dylib, we give it hidden visibility:
3012
3013	.. code-block:: c++
3014
3015	// in <string>
3016	template <class CharT>
3017	class basic_string {
3018	public:
3019	__attribute__((__visibility__("hidden")))
3020	const value_type* data() const noexcept { ... }
3021	};
3022
3023	template class basic_string<char>;
3024
3025	Since an explicit template instantiation declaration for ``basic_string<char>``
3026	is provided, the compiler is free to assume that ``basic_string<char>::data()``
3027	will be provided by another translation unit, and it is free to produce an
3028	external call to this function. However, since ``data()`` has hidden visibility
3029	and the explicit template instantiation is provided in a shared library (as
3030	opposed to simply another translation unit), ``basic_string<char>::data()``
3031	won't be found and a link error will ensue. This happens because the compiler
3032	assumes that ``basic_string<char>::data()`` is part of the explicit template
3033	instantiation declaration, when it really isn't. To tell the compiler that
3034	``data()`` is not part of the explicit template instantiation declaration, the
3035	``exclude_from_explicit_instantiation`` attribute can be used:
3036
3037	.. code-block:: c++
3038
3039	// in <string>
3040	template <class CharT>
3041	class basic_string {
3042	public:
3043	__attribute__((__visibility__("hidden")))
3044	__attribute__((exclude_from_explicit_instantiation))
3045	const value_type* data() const noexcept { ... }
3046	};
3047
3048	template class basic_string<char>;
3049
3050	Now, the compiler won't assume that ``basic_string<char>::data()`` is provided
3051	externally despite there being an explicit template instantiation declaration:
3052	the compiler will implicitly instantiate ``basic_string<char>::data()`` in the
3053	TUs where it is used.
3054
3055	This attribute can be used on static and non-static member functions of class
3056	templates, static data members of class templates and member classes of class
3057	templates.)reST";
3058
3059	static const char AttrDoc_ExplicitInit[] = R"reST(The ``clang::require_explicit_initialization`` attribute indicates that a
3060	field of an aggregate must be initialized explicitly by the user when an object
3061	of the aggregate type is constructed. The attribute supports both C and C++,
3062	but its usage is invalid on non-aggregates.
3063
3064	Note that this attribute is not a memory safety feature, and is not intended
3065	to guard against use of uninitialized memory.
3066
3067	Rather, it is intended for use in "parameter-objects", used to simulate,
3068	for example, the passing of named parameters.
3069	Except inside unevaluated contexts, the attribute generates a warning when
3070	explicit initializers for such variables are not provided (this occurs
3071	regardless of whether any in-class field initializers exist):
3072
3073	.. code-block:: c++
3074
3075	struct Buffer {
3076	void *address [[clang::require_explicit_initialization]];
3077	size_t length [[clang::require_explicit_initialization]] = 0;
3078	};
3079
3080	struct ArrayIOParams {
3081	size_t count [[clang::require_explicit_initialization]];
3082	size_t element_size [[clang::require_explicit_initialization]];
3083	int flags = 0;
3084	};
3085
3086	size_t ReadArray(FILE *file, struct Buffer buffer,
3087	struct ArrayIOParams params);
3088
3089	int main() {
3090	unsigned int buf[512];
3091	ReadArray(stdin, {
3092	buf
3093	// warning: field 'length' is not explicitly initialized
3094	}, {
3095	.count = sizeof(buf) / sizeof(*buf),
3096	// warning: field 'element_size' is not explicitly initialized
3097	// (Note that a missing initializer for 'flags' is not diagnosed, because
3098	// the field is not marked as requiring explicit initialization.)
3099	});
3100	})reST";
3101
3102	static const char AttrDoc_ExtVectorType[] = R"reST(The ``ext_vector_type(N)`` attribute specifies that a type is a vector with N
3103	elements, directly mapping to an LLVM vector type. Originally from OpenCL, it
3104	allows element access the array subscript operator ``[]``, ``sN`` where N is
3105	a hexadecimal value, or ``x, y, z, w`` for graphics-style indexing.
3106	This attribute enables efficient SIMD operations and is usable in
3107	general-purpose code.
3108
3109	.. code-block:: c++
3110
3111	template <typename T, uint32_t N>
3112	constexpr T simd_reduce(T [[clang::ext_vector_type(N)]] v) {
3113	static_assert((N & (N - 1)) == 0, "N must be a power of two");
3114	if constexpr (N == 1)
3115	return v[0];
3116	else
3117	return simd_reduce<T, N / 2>(v.hi + v.lo);
3118	}
3119
3120	The vector type also supports swizzling up to sixteen elements. This can be done
3121	using the object accessors. The OpenCL documentation lists all of the accepted
3122	values.
3123
3124	.. code-block:: c++
3125
3126	using f16_x16 = _Float16 __attribute__((ext_vector_type(16)));
3127
3128	f16_x16 reverse(f16_x16 v) { return v.sfedcba9876543210; }
3129
3130	See the OpenCL documentation for some more complete examples.)reST";
3131
3132	static const char AttrDoc_ExternalSourceSymbol[] = R"reST(The ``external_source_symbol`` attribute specifies that a declaration originates
3133	from an external source and describes the nature of that source.
3134
3135	The fact that Clang is capable of recognizing declarations that were defined
3136	externally can be used to provide better tooling support for mixed-language
3137	projects or projects that rely on auto-generated code. For instance, an IDE that
3138	uses Clang and that supports mixed-language projects can use this attribute to
3139	provide a correct 'jump-to-definition' feature. For a concrete example,
3140	consider a protocol that's defined in a Swift file:
3141
3142	.. code-block:: swift
3143
3144	@objc public protocol SwiftProtocol {
3145	func method()
3146	}
3147
3148	This protocol can be used from Objective-C code by including a header file that
3149	was generated by the Swift compiler. The declarations in that header can use
3150	the ``external_source_symbol`` attribute to make Clang aware of the fact
3151	that ``SwiftProtocol`` actually originates from a Swift module:
3152
3153	.. code-block:: objc
3154
3155	__attribute__((external_source_symbol(language="Swift",defined_in="module")))
3156	@protocol SwiftProtocol
3157	@required
3158	- (void) method;
3159	@end
3160
3161	Consequently, when 'jump-to-definition' is performed at a location that
3162	references ``SwiftProtocol``, the IDE can jump to the original definition in
3163	the Swift source file rather than jumping to the Objective-C declaration in the
3164	auto-generated header file.
3165
3166	The ``external_source_symbol`` attribute is a comma-separated list that includes
3167	clauses that describe the origin and the nature of the particular declaration.
3168	Those clauses can be:
3169
3170	language=\ string-literal
3171	The name of the source language in which this declaration was defined.
3172
3173	defined_in=\ string-literal
3174	The name of the source container in which the declaration was defined. The
3175	exact definition of source container is language-specific, e.g. Swift's
3176	source containers are modules, so ``defined_in`` should specify the Swift
3177	module name.
3178
3179	USR=\ string-literal
3180	String that specifies a unified symbol resolution (USR) value for this
3181	declaration. USR string uniquely identifies this particular declaration, and
3182	is typically used when constructing an index of a codebase.
3183	The USR value in this attribute is expected to be generated by an external
3184	compiler that compiled the native declaration using its original source
3185	language. The exact format of the USR string and its other attributes
3186	are determined by the specification of this declaration's source language.
3187	When not specified, Clang's indexer will use the Clang USR for this symbol.
3188	User can query to see if Clang supports the use of the ``USR`` clause in
3189	the ``external_source_symbol`` attribute with
3190	``__has_attribute(external_source_symbol) >= 20230206``.
3191
3192	generated_declaration
3193	This declaration was automatically generated by some tool.
3194
3195	The clauses can be specified in any order. The clauses that are listed above are
3196	all optional, but the attribute has to have at least one clause.)reST";
3197
3198	static const char AttrDoc_FallThrough[] = R"reST(The ``fallthrough`` (or ``clang::fallthrough``) attribute is used
3199	to annotate intentional fall-through
3200	between switch labels. It can only be applied to a null statement placed at a
3201	point of execution between any statement and the next switch label. It is
3202	common to mark these places with a specific comment, but this attribute is
3203	meant to replace comments with a more strict annotation, which can be checked
3204	by the compiler. This attribute doesn't change semantics of the code and can
3205	be used wherever an intended fall-through occurs. It is designed to mimic
3206	control-flow statements like ``break;``, so it can be placed in most places
3207	where ``break;`` can, but only if there are no statements on the execution path
3208	between it and the next switch label.
3209
3210	By default, Clang does not warn on unannotated fallthrough from one ``switch``
3211	case to another. Diagnostics on fallthrough without a corresponding annotation
3212	can be enabled with the ``-Wimplicit-fallthrough`` argument.
3213
3214	Here is an example:
3215
3216	.. code-block:: c++
3217
3218	// compile with -Wimplicit-fallthrough
3219	switch (n) {
3220	case 22:
3221	case 33: // no warning: no statements between case labels
3222	f();
3223	case 44: // warning: unannotated fall-through
3224	g();
3225	[[clang::fallthrough]];
3226	case 55: // no warning
3227	if (x) {
3228	h();
3229	break;
3230	}
3231	else {
3232	i();
3233	[[clang::fallthrough]];
3234	}
3235	case 66: // no warning
3236	p();
3237	[[clang::fallthrough]]; // warning: fallthrough annotation does not
3238	// directly precede case label
3239	q();
3240	case 77: // warning: unannotated fall-through
3241	r();
3242	})reST";
3243
3244	static const char AttrDoc_FastCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
3245	function to use ECX and EDX as register parameters and clear parameters off of
3246	the stack on return. This convention does not support variadic calls or
3247	unprototyped functions in C, and has no effect on x86_64 targets. This calling
3248	convention is supported primarily for compatibility with existing code. Users
3249	seeking register parameters should use the ``regparm`` attribute, which does
3250	not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN.
3251
3252	.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx)reST";
3253
3254	static const char AttrDoc_Final[] = R"reST()reST";
3255
3256	static const char AttrDoc_FlagEnum[] = R"reST(This attribute can be added to an enumerator to signal to the compiler that it
3257	is intended to be used as a flag type. This will cause the compiler to assume
3258	that the range of the type includes all of the values that you can get by
3259	manipulating bits of the enumerator when issuing warnings.)reST";
3260
3261	static const char AttrDoc_Flatten[] = R"reST(The ``flatten`` attribute causes calls within the attributed function to
3262	be inlined unless it is impossible to do so, for example if the body of the
3263	callee is unavailable or if the callee has the ``noinline`` attribute.)reST";
3264
3265	static const char AttrDoc_Format[] = R"reST(Clang supports the ``format`` attribute, which indicates that the function
3266	accepts (among other possibilities) a ``printf`` or ``scanf``-like format string
3267	and corresponding arguments or a ``va_list`` that contains these arguments.
3268
3269	Please see `GCC documentation about format attribute
3270	<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
3271	about attribute syntax.
3272
3273	Clang implements two kinds of checks with this attribute.
3274
3275	#. Clang checks that the function with the ``format`` attribute is called with
3276	a format string that uses format specifiers that are allowed, and that
3277	arguments match the format string. This is the ``-Wformat`` warning, it is
3278	on by default.
3279
3280	#. Clang checks that the format string argument is a literal string. This is
3281	the ``-Wformat-nonliteral`` warning, it is off by default.
3282
3283	Clang implements this mostly the same way as GCC, but there is a difference
3284	for functions that accept a ``va_list`` argument (for example, ``vprintf``).
3285	GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
3286	functions. Clang does not warn if the format string comes from a function
3287	parameter, where the function is annotated with a compatible attribute,
3288	otherwise it warns. For example:
3289
3290	.. code-block:: c
3291
3292	__attribute__((__format__ (__scanf__, 1, 3)))
3293	void foo(const char* s, char *buf, ...) {
3294	va_list ap;
3295	va_start(ap, buf);
3296
3297	vprintf(s, ap); // warning: format string is not a string literal
3298	}
3299
3300	In this case we warn because ``s`` contains a format string for a
3301	``scanf``-like function, but it is passed to a ``printf``-like function.
3302
3303	If the attribute is removed, clang still warns, because the format string is
3304	not a string literal.
3305
3306	Another example:
3307
3308	.. code-block:: c
3309
3310	__attribute__((__format__ (__printf__, 1, 3)))
3311	void foo(const char* s, char *buf, ...) {
3312	va_list ap;
3313	va_start(ap, buf);
3314
3315	vprintf(s, ap); // warning
3316	}
3317
3318	In this case Clang does not warn because the format string ``s`` and
3319	the corresponding arguments are annotated. If the arguments are
3320	incorrect, the caller of ``foo`` will receive a warning.
3321
3322	As an extension to GCC's behavior, Clang accepts the ``format`` attribute on
3323	non-variadic functions. Clang checks non-variadic format functions for the same
3324	classes of issues that can be found on variadic functions, as controlled by the
3325	same warning flags, except that the types of formatted arguments is forced by
3326	the function signature. For example:
3327
3328	.. code-block:: c
3329
3330	__attribute__((__format__(__printf__, 1, 2)))
3331	void fmt(const char s, const char a, int b);
3332
3333	void bar(void) {
3334	fmt("%s %i", "hello", 123); // OK
3335	fmt("%i %g", "hello", 123); // warning: arguments don't match format
3336	extern const char *fmt;
3337	fmt(fmt, "hello", 123); // warning: format string is not a string literal
3338	}
3339
3340	When using the format attribute on a variadic function, the first data parameter
3341	_must_ be the index of the ellipsis in the parameter list. Clang will generate
3342	a diagnostic otherwise, as it wouldn't be possible to forward that argument list
3343	to `printf`-family functions. For instance, this is an error:
3344
3345	.. code-block:: c
3346
3347	__attribute__((__format__(__printf__, 1, 2)))
3348	void fmt(const char *s, int b, ...);
3349	// ^ error: format attribute parameter 3 is out of bounds
3350	// (must be __printf__, 1, 3)
3351
3352	Using the ``format`` attribute on a non-variadic function emits a GCC
3353	compatibility diagnostic.)reST";
3354
3355	static const char AttrDoc_FormatArg[] = R"reST(No documentation.)reST";
3356
3357	static const char AttrDoc_FormatMatches[] = R"reST(The ``format`` attribute is the basis for the enforcement of diagnostics in the
3358	``-Wformat`` family, but it only handles the case where the format string is
3359	passed along with the arguments it is going to format. It cannot handle the case
3360	where the format string and the format arguments are passed separately from each
3361	other. For instance:
3362
3363	.. code-block:: c
3364
3365	static const char *first_name;
3366	static double todays_temperature;
3367	static int wind_speed;
3368
3369	void say_hi(const char *fmt) {
3370	printf(fmt, first_name, todays_temperature);
3371	// ^ warning: format string is not a string literal
3372	printf(fmt, first_name, wind_speed);
3373	// ^ warning: format string is not a string literal
3374	}
3375
3376	int main() {
3377	say_hi("hello %s, it is %g degrees outside");
3378	say_hi("hello %s, it is %d degrees outside!");
3379	// ^ no diagnostic, but %d cannot format doubles
3380	}
3381
3382	In this example, ``fmt`` is expected to format a ``const char *`` and a
3383	``double``, but these values are not passed to ``say_hi``. Without the
3384	``format`` attribute (which cannot apply in this case), the -Wformat-nonliteral
3385	diagnostic unnecessarily triggers in the body of ``say_hi``, and incorrect
3386	``say_hi`` call sites do not trigger a diagnostic.
3387
3388	To complement the ``format`` attribute, Clang also defines the
3389	``format_matches`` attribute. Its syntax is similar to the ``format``
3390	attribute's, but instead of taking the index of the first formatted value
3391	argument, it takes a C string literal with the expected specifiers:
3392
3393	.. code-block:: c
3394
3395	static const char *first_name;
3396	static double todays_temperature;
3397	static int wind_speed;
3398
3399	__attribute__((__format_matches__(printf, 1, "%s %g")))
3400	void say_hi(const char *fmt) {
3401	printf(fmt, first_name, todays_temperature); // no dignostic
3402	printf(fmt, first_name, wind_speed); // warning: format specifies type 'int' but the argument has type 'double'
3403	}
3404
3405	int main() {
3406	say_hi("hello %s, it is %g degrees outside");
3407	say_hi("it is %g degrees outside, have a good day %s!");
3408	// warning: format specifies 'double' where 'const char *' is required
3409	// warning: format specifies 'const char *' where 'double' is required
3410	}
3411
3412	The third argument to ``format_matches`` is expected to evaluate to a **C string
3413	literal** even when the format string would normally be a different type for the
3414	given flavor, like a ``CFStringRef`` or a ``NSString *``.
3415
3416	The only requirement on the format string literal is that it has specifiers
3417	that are compatible with the arguments that will be used. It can contain
3418	arbitrary non-format characters. For instance, for the purposes of compile-time
3419	validation, ``"%s scored %g%% on her test"`` and ``"%s%g"`` are interchangeable
3420	as the format string argument. As a means of self-documentation, users may
3421	prefer the former when it provides a useful example of an expected format
3422	string.
3423
3424	In the implementation of a function with the ``format_matches`` attribute,
3425	format verification works as if the format string was identical to the one
3426	specified in the attribute.
3427
3428	.. code-block:: c
3429
3430	__attribute__((__format_matches__(printf, 1, "%s %g")))
3431	void say_hi(const char *fmt) {
3432	printf(fmt, "person", 546);
3433	// ^ warning: format specifies type 'double' but the
3434	// argument has type 'int'
3435	// note: format string is defined here:
3436	// __attribute__((__format_matches__(printf, 1, "%s %g")))
3437	// ^~
3438	}
3439
3440
3441	At the call sites of functions with the ``format_matches`` attribute, format
3442	verification instead compares the two format strings to evaluate their
3443	equivalence. Each format flavor defines equivalence between format specifiers.
3444	Generally speaking, two specifiers are equivalent if they format the same type.
3445	For instance, in the ``printf`` flavor, ``%2i`` and ``%-0.5d`` are compatible.
3446	When ``-Wformat-signedness`` is disabled, ``%d`` and ``%u`` are compatible. For
3447	a negative example, ``%ld`` is incompatible with ``%d``.
3448
3449	Do note the following un-obvious cases:
3450
3451	* Passing ``NULL`` as the format string does not trigger format diagnostics.
3452	* When the format string is not NULL, it cannot _miss_ specifiers, even in
3453	trailing positions. For instance, ``%d`` is not accepted when the required
3454	format is ``%d %d %d``.
3455	* While checks for the ``format`` attribute tolerate sone size mismatches
3456	that standard argument promotion renders immaterial (such as formatting an
3457	``int`` with ``%hhd``, which specifies a ``char``-sized integer), checks for
3458	``format_matches`` require specified argument sizes to match exactly.
3459	* Format strings expecting a variable modifier (such as ``%*s``) are
3460	incompatible with format strings that would itemize the variable modifiers
3461	(such as ``%i %s``), even if the two specify ABI-compatible argument lists.
3462	* All pointer specifiers, modifiers aside, are mutually incompatible. For
3463	instance, ``%s`` is not compatible with ``%p``, and ``%p`` is not compatible
3464	with ``%n``, and ``%hhn`` is incompatible with ``%s``, even if the pointers
3465	are ABI-compatible or identical on the selected platform. However, ``%0.5s``
3466	is compatible with ``%s``, since the difference only exists in modifier flags.
3467	This is not overridable with ``-Wformat-pedantic`` or its inverse, which
3468	control similar behavior in ``-Wformat``.
3469
3470	At this time, clang implements ``format_matches`` only for format types in the
3471	``printf`` family. This includes variants such as Apple's NSString format and
3472	the FreeBSD ``kprintf``, but excludes ``scanf``. Using a known but unsupported
3473	format silently fails in order to be compatible with other implementations that
3474	would support these formats.)reST";
3475
3476	static const char AttrDoc_FunctionReturnThunks[] = R"reST(The attribute ``function_return`` can replace return instructions with jumps to
3477	target-specific symbols. This attribute supports 2 possible values,
3478	corresponding to the values supported by the ``-mfunction-return=`` command
3479	line flag:
3480
3481	* ``__attribute__((function_return("keep")))`` to disable related transforms.
3482	This is useful for undoing global setting from ``-mfunction-return=`` locally
3483	for individual functions.
3484	* ``__attribute__((function_return("thunk-extern")))`` to replace returns with
3485	jumps, while NOT emitting the thunk.
3486
3487	The values ``thunk`` and ``thunk-inline`` from GCC are not supported.
3488
3489	The symbol used for ``thunk-extern`` is target specific:
3490	* X86: ``__x86_return_thunk``
3491
3492	As such, this function attribute is currently only supported on X86 targets.)reST";
3493
3494	static const char AttrDoc_GCCStruct[] = R"reST(The ``ms_struct`` and ``gcc_struct`` attributes request the compiler to enter a
3495	special record layout compatibility mode which mimics the layout of Microsoft or
3496	Itanium C++ ABI respectively. Obviously, if the current C++ ABI matches the
3497	requested ABI, the attribute does nothing. However, if it does not, annotated
3498	structure or class is laid out in a special compatibility mode, which slightly
3499	changes offsets for fields and bit-fields. The intention is to match the layout
3500	of the requested ABI for structures which only use C features.
3501
3502	Note that the default behavior can be controlled by ``-mms-bitfields`` and
3503	``-mno-ms-bitfields`` switches and via ``#pragma ms_struct``.
3504
3505	The primary difference is for bitfields, where the MS variant only packs
3506	adjacent fields into the same allocation unit if they have integral types
3507	of the same size, while the GCC/Itanium variant packs all fields in a bitfield
3508	tightly.)reST";
3509
3510	static const char AttrDoc_GNUInline[] = R"reST(The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline
3511	semantics, meaning:
3512
3513	* If any declaration that is declared ``inline`` is not declared ``extern``,
3514	then the ``inline`` keyword is just a hint. In particular, an out-of-line
3515	definition is still emitted for a function with external linkage, even if all
3516	call sites are inlined, unlike in C99 and C++ inline semantics.
3517
3518	* If all declarations that are declared ``inline`` are also declared
3519	``extern``, then the function body is present only for inlining and no
3520	out-of-line version is emitted.
3521
3522	Some important consequences: ``static inline`` emits an out-of-line
3523	version if needed, a plain ``inline`` definition emits an out-of-line version
3524	always, and an ``extern inline`` definition (in a header) followed by a
3525	(non-``extern``) ``inline`` declaration in a source file emits an out-of-line
3526	version of the function in that source file but provides the function body for
3527	inlining to all includers of the header.
3528
3529	Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or
3530	``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually
3531	exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline``
3532	function attribute can be used to get GNU inline semantics on a per function
3533	basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is
3534	already being compiled with GNU inline semantics as the implied default. It is
3535	unspecified which macro is defined in a C++ compilation.
3536
3537	GNU inline semantics are the default behavior with ``-std=gnu89``,
3538	``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``.)reST";
3539
3540	static const char AttrDoc_GuardedBy[] = R"reST(No documentation.)reST";
3541
3542	static const char AttrDoc_GuardedVar[] = R"reST(No documentation.)reST";
3543
3544	static const char AttrDoc_HIPManaged[] = R"reST(The ``__managed__`` attribute can be applied to a global variable declaration in HIP.
3545	A managed variable is emitted as an undefined global symbol in the device binary and is
3546	registered by ``__hipRegisterManagedVariable`` in init functions. The HIP runtime allocates
3547	managed memory and uses it to define the symbol when loading the device binary.
3548	A managed variable can be accessed in both device and host code.)reST";
3549
3550	static const char AttrDoc_HLSLAppliedSemantic[] = R"reST()reST";
3551
3552	static const char AttrDoc_HLSLContainedType[] = R"reST()reST";
3553
3554	static const char AttrDoc_HLSLControlFlowHint[] = R"reST()reST";
3555
3556	static const char AttrDoc_HLSLGroupSharedAddressSpace[] = R"reST(HLSL enables threads of a compute shader to exchange values via shared memory.
3557	HLSL provides barrier primitives such as GroupMemoryBarrierWithGroupSync,
3558	and so on to ensure the correct ordering of reads and writes to shared memory
3559	in the shader and to avoid data races.
3560	Here's an example to declare a groupshared variable.
3561	.. code-block:: c++
3562
3563	groupshared GSData data[551];
3564
3565	The full documentation is available here: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-syntax#group-shared)reST";
3566
3567	static const char AttrDoc_HLSLIsCounter[] = R"reST()reST";
3568
3569	static const char AttrDoc_HLSLLoopHint[] = R"reST(The ``[loop]`` directive allows loop optimization hints to be
3570	specified for the subsequent loop. The directive allows unrolling to
3571	be disabled and is not compatible with [unroll(x)].
3572
3573	Specifying the parameter, ``[loop]``, directs the
3574	unroller to not unroll the loop.
3575
3576	.. code-block:: hlsl
3577
3578	[loop]
3579	for (...) {
3580	...
3581	}
3582
3583	.. code-block:: hlsl
3584
3585	[loop]
3586	while (...) {
3587	...
3588	}
3589
3590	.. code-block:: hlsl
3591
3592	[loop]
3593	do {
3594	...
3595	} while (...)
3596
3597	See `hlsl loop extensions <https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-for>`_
3598	for details.)reST";
3599
3600	static const char AttrDoc_HLSLNumThreads[] = R"reST(The ``numthreads`` attribute applies to HLSL shaders where explcit thread counts
3601	are required. The ``X``, ``Y``, and ``Z`` values provided to the attribute
3602	dictate the thread id. Total number of threads executed is ``X * Y * Z``.
3603
3604	The full documentation is available here: https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/sm5-attributes-numthreads)reST";
3605
3606	static const char AttrDoc_HLSLPackOffset[] = R"reST(The packoffset attribute is used to change the layout of a cbuffer.
3607	Attribute spelling in HLSL is: ``packoffset( c[Subcomponent][.component] )``.
3608	A subcomponent is a register number, which is an integer. A component is in the form of [.xyzw].
3609
3610	Examples:
3611
3612	.. code-block:: hlsl
3613
3614	cbuffer A {
3615	float3 a : packoffset(c0.y);
3616	float4 b : packoffset(c4);
3617	}
3618
3619	The full documentation is available here: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-packoffset)reST";
3620
3621	static const char AttrDoc_HLSLParamModifier[] = R"reST(HLSL function parameters are passed by value. Parameter declarations support
3622	three qualifiers to denote parameter passing behavior. The three qualifiers are
3623	`in`, `out` and `inout`.
3624
3625	Parameters annotated with `in` or with no annotation are passed by value from
3626	the caller to the callee.
3627
3628	Parameters annotated with `out` are written to the argument after the callee
3629	returns (Note: arguments values passed into `out` parameters are not copied
3630	into the callee).
3631
3632	Parameters annotated with `inout` are copied into the callee via a temporary,
3633	and copied back to the argument after the callee returns.)reST";
3634
3635	static const char AttrDoc_HLSLParsedSemantic[] = R"reST()reST";
3636
3637	static const char AttrDoc_HLSLROV[] = R"reST()reST";
3638
3639	static const char AttrDoc_HLSLRawBuffer[] = R"reST()reST";
3640
3641	static const char AttrDoc_HLSLResourceBinding[] = R"reST(The resource binding attribute sets the virtual register and logical register space for a resource.
3642	Attribute spelling in HLSL is: ``register(slot [, space])``.
3643	``slot`` takes the format ``[type][number]``,
3644	where ``type`` is a single character specifying the resource type and ``number`` is the virtual register number.
3645
3646	Register types are:
3647	t for shader resource views (SRV),
3648	s for samplers,
3649	u for unordered access views (UAV),
3650	b for constant buffer views (CBV).
3651
3652	Register space is specified in the format ``space[number]`` and defaults to ``space0`` if omitted.
3653	Here're resource binding examples with and without space:
3654
3655	.. code-block:: hlsl
3656
3657	RWBuffer<float> Uav : register(u3, space1);
3658	Buffer<float> Buf : register(t1);
3659
3660	The full documentation is available here: https://docs.microsoft.com/en-us/windows/win32/direct3d12/resource-binding-in-hlsl)reST";
3661
3662	static const char AttrDoc_HLSLResourceClass[] = R"reST()reST";
3663
3664	static const char AttrDoc_HLSLResourceDimension[] = R"reST()reST";
3665
3666	static const char AttrDoc_HLSLShader[] = R"reST(The ``shader`` type attribute applies to HLSL shader entry functions to
3667	identify the shader type for the entry function.
3668	The syntax is:
3669
3670	.. code-block:: text
3671
3672	``[shader(string-literal)]``
3673
3674	where the string literal is one of: "pixel", "vertex", "geometry", "hull",
3675	"domain", "compute", "raygeneration", "intersection", "anyhit", "closesthit",
3676	"miss", "callable", "mesh", "amplification". Normally the shader type is set
3677	by shader target with the ``-T`` option like ``-Tps_6_1``. When compiling to a
3678	library target like ``lib_6_3``, the shader type attribute can help the
3679	compiler to identify the shader type. It is mostly used by Raytracing shaders
3680	where shaders must be compiled into a library and linked at runtime.)reST";
3681
3682	static const char AttrDoc_HLSLUnparsedSemantic[] = R"reST()reST";
3683
3684	static const char AttrDoc_HLSLVkBinding[] = R"reST(The ``[[vk::binding]]`` attribute allows you to explicitly specify the descriptor
3685	set and binding for a resource when targeting SPIR-V. This is particularly
3686	useful when you need different bindings for SPIR-V and DXIL, as the ``register``
3687	attribute can be used for DXIL-specific bindings.
3688
3689	The attribute takes two integer arguments: the binding and the descriptor set.
3690	The descriptor set is optional and defaults to 0 if not provided.
3691
3692	.. code-block:: c++
3693
3694	// A structured buffer with binding 23 in descriptor set 102.
3695	[[vk::binding(23, 102)]] StructuredBuffer<float> Buf;
3696
3697	// A structured buffer with binding 14 in descriptor set 0.
3698	[[vk::binding(14)]] StructuredBuffer<float> Buf2;
3699
3700	// A cbuffer with binding 1 in descriptor set 2.
3701	[[vk::binding(1, 2)]] cbuffer MyCBuffer {
3702	float4x4 worldViewProj;
3703	};)reST";
3704
3705	static const char AttrDoc_HLSLVkConstantId[] = R"reST(The ``vk::constant_id`` attribute specifies the id for a SPIR-V specialization
3706	constant. The attribute applies to const global scalar variables. The variable must be initialized with a C++11 constexpr.
3707	In SPIR-V, the
3708	variable will be replaced with an `OpSpecConstant` with the given id.
3709	The syntax is:
3710
3711	.. code-block:: text
3712
3713	``[[vk::constant_id(<Id>)]] const T Name = <Init>``)reST";
3714
3715	static const char AttrDoc_HLSLVkExtBuiltinInput[] = R"reST(Vulkan shaders have `Input` builtins. Those variables are externally
3716	initialized by the driver/pipeline, but each copy is private to the current
3717	lane.
3718
3719	Those builtins can be declared using the `[[vk::ext_builtin_input]]` attribute
3720	like follows:
3721
3722	.. code-block:: c++
3723
3724	[[vk::ext_builtin_input(/* WorkgroupId */ 26)]]
3725	static const uint3 groupid;
3726
3727	This variable will be lowered into a module-level variable, with the `Input`
3728	storage class, and the `BuiltIn 26` decoration.
3729
3730	The full documentation for this inline SPIR-V attribute can be found here:
3731	https://github.com/microsoft/hlsl-specs/blob/main/proposals/0011-inline-spirv.md)reST";
3732
3733	static const char AttrDoc_HLSLVkLocation[] = R"reST(Attribute used for specifying the location number for the stage input/output
3734	variables. Allowed on function parameters, function returns, and struct
3735	fields. This parameter has no effect when used outside of an entrypoint
3736	parameter/parameter field/return value.
3737
3738	This attribute maps to the 'Location' SPIR-V decoration.)reST";
3739
3740	static const char AttrDoc_HLSLVkPushConstant[] = R"reST(Vulkan shaders have `PushConstants`
3741
3742	The ``[[vk::push_constant]]`` attribute allows you to declare this
3743	global variable as a push constant when targeting Vulkan.
3744	This attribute is ignored otherwise.
3745
3746	This attribute must be applied to the variable, not underlying type.
3747	The variable type must be a struct, per the requirements of Vulkan, "there
3748	must be no more than one push constant block statically used per shader entry
3749	point.")reST";
3750
3751	static const char AttrDoc_HLSLWaveSize[] = R"reST(The ``WaveSize`` attribute specify a wave size on a shader entry point in order
3752	to indicate either that a shader depends on or strongly prefers a specific wave
3753	size.
3754	There're 2 versions of the attribute: ``WaveSize`` and ``RangedWaveSize``.
3755	The syntax for ``WaveSize`` is:
3756
3757	.. code-block:: text
3758
3759	``[WaveSize(<numLanes>)]``
3760
3761	The allowed wave sizes that an HLSL shader may specify are the powers of 2
3762	between 4 and 128, inclusive.
3763	In other words, the set: [4, 8, 16, 32, 64, 128].
3764
3765	The syntax for ``RangedWaveSize`` is:
3766
3767	.. code-block:: text
3768
3769	``[WaveSize(<minWaveSize>, <maxWaveSize>, [prefWaveSize])]``
3770
3771	Where minWaveSize is the minimum wave size supported by the shader representing
3772	the beginning of the allowed range, maxWaveSize is the maximum wave size
3773	supported by the shader representing the end of the allowed range, and
3774	prefWaveSize is the optional preferred wave size representing the size expected
3775	to be the most optimal for this shader.
3776
3777	``WaveSize`` is available for HLSL shader model 6.6 and later.
3778	``RangedWaveSize`` available for HLSL shader model 6.8 and later.
3779
3780	The full documentation is available here: https://microsoft.github.io/DirectX-Specs/d3d/HLSL_SM_6_6_WaveSize.html
3781	and https://microsoft.github.io/hlsl-specs/proposals/0013-wave-size-range.html)reST";
3782
3783	static const char AttrDoc_Hot[] = R"reST(``__attribute__((hot))`` marks a function as hot, as a manual alternative to PGO hotness data.
3784	If PGO data is available, the annotation ``__attribute__((hot))`` overrides the profile count based hotness (unlike ``__attribute__((cold))``).)reST";
3785
3786	static const char AttrDoc_HybridPatchable[] = R"reST(The ``hybrid_patchable`` attribute declares an ARM64EC function with an additional
3787	x86-64 thunk, which may be patched at runtime.
3788
3789	For more information see
3790	`ARM64EC ABI documentation <https://learn.microsoft.com/en-us/windows/arm/arm64ec-abi>`_.)reST";
3791
3792	static const char AttrDoc_IBAction[] = R"reST(No documentation.)reST";
3793
3794	static const char AttrDoc_IBOutlet[] = R"reST(No documentation.)reST";
3795
3796	static const char AttrDoc_IBOutletCollection[] = R"reST(No documentation.)reST";
3797
3798	static const char AttrDoc_IFunc[] = R"reST(``__attribute__((ifunc("resolver")))`` is used to mark that the address of a
3799	declaration should be resolved at runtime by calling a resolver function.
3800
3801	The symbol name of the resolver function is given in quotes. A function with
3802	this name (after mangling) must be defined in the current translation unit; it
3803	may be ``static``. The resolver function should return a pointer.
3804
3805	The ``ifunc`` attribute may only be used on a function declaration. A function
3806	declaration with an ``ifunc`` attribute is considered to be a definition of the
3807	declared entity. The entity must not have weak linkage; for example, in C++,
3808	it cannot be applied to a declaration if a definition at that location would be
3809	considered inline.
3810
3811	Not all targets support this attribute:
3812
3813	- ELF target support depends on both the linker and runtime linker, and is
3814	available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc
3815	v2.11.1 and later, and FreeBSD 9.1 and later.
3816	- Mach-O targets support it, but with slightly different semantics: the resolver
3817	is run at first call, instead of at load time by the runtime linker.
3818	- Windows target supports it on AArch64, but with different semantics: the
3819	``ifunc`` is replaced with a global function pointer, and the call is replaced
3820	with an indirect call. The function pointer is initialized by a constructor
3821	that calls the resolver.
3822	- Baremetal target supports it on AVR.
3823	- Other targets currently do not support this attribute.)reST";
3824
3825	static const char AttrDoc_InferredNoReturn[] = R"reST()reST";
3826
3827	static const char AttrDoc_InitPriority[] = R"reST(In C++, the order in which global variables are initialized across translation
3828	units is unspecified, unlike the ordering within a single translation unit. The
3829	``init_priority`` attribute allows you to specify a relative ordering for the
3830	initialization of objects declared at namespace scope in C++ within a single
3831	linked image on supported platforms. The priority is given as an integer constant
3832	expression between 101 and 65535 (inclusive). Priorities outside of that range are
3833	reserved for use by the implementation. A lower value indicates a higher priority
3834	of initialization. Note that only the relative ordering of values is important.
3835	For example:
3836
3837	.. code-block:: c++
3838
3839	struct SomeType { SomeType(); };
3840	__attribute__((init_priority(200))) SomeType Obj1;
3841	__attribute__((init_priority(101))) SomeType Obj2;
3842
3843	``Obj2`` will be initialized before ``Obj1`` despite the usual order of
3844	initialization being the opposite.
3845
3846	Note that this attribute does not control the initialization order of objects
3847	across final linked image boundaries like shared objects and executables.
3848
3849	On Windows, ``init_seg(compiler)`` is represented with a priority of 200 and
3850	``init_seg(library)`` is represented with a priority of 400. ``init_seg(user)``
3851	uses the default 65535 priority.
3852
3853	On MachO platforms, this attribute also does not control the order of initialization
3854	across translation units, where it only affects the order within a single TU.
3855
3856	This attribute is only supported for C++ and Objective-C++ and is ignored in
3857	other language modes. Currently, this attribute is not implemented on z/OS.)reST";
3858
3859	static const char AttrDoc_InitSeg[] = R"reST(The attribute applied by ``pragma init_seg()`` controls the section into
3860	which global initialization function pointers are emitted. It is only
3861	available with ``-fms-extensions``. Typically, this function pointer is
3862	emitted into ``.CRT$XCU`` on Windows. The user can change the order of
3863	initialization by using a different section name with the same
3864	``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
3865	after the standard ``.CRT$XCU`` sections. See the init_seg_
3866	documentation on MSDN for more information.
3867
3868	.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx)reST";
3869
3870	static const char AttrDoc_IntelOclBicc[] = R"reST(No documentation.)reST";
3871
3872	static const char AttrDoc_InternalLinkage[] = R"reST(The ``internal_linkage`` attribute changes the linkage type of the declaration
3873	to internal. This is similar to C-style ``static``, but can be used on classes
3874	and class methods. When applied to a class definition, this attribute affects
3875	all methods and static data members of that class. This can be used to contain
3876	the ABI of a C++ library by excluding unwanted class methods from the export
3877	tables.)reST";
3878
3879	static const char AttrDoc_LTOVisibilityPublic[] = R"reST(See :doc:`LTOVisibility`.)reST";
3880
3881	static const char AttrDoc_LayoutVersion[] = R"reST(The layout_version attribute requests that the compiler utilize the class
3882	layout rules of a particular compiler version.
3883	This attribute only applies to struct, class, and union types.
3884	It is only supported when using the Microsoft C++ ABI.)reST";
3885
3886	static const char AttrDoc_Leaf[] = R"reST(The ``leaf`` attribute is used as a compiler hint to improve dataflow analysis
3887	in library functions. Functions marked with the ``leaf`` attribute are not allowed
3888	to jump back into the caller's translation unit, whether through invoking a
3889	callback function, an external function call, use of ``longjmp``, or other means.
3890	Therefore, they cannot use or modify any data that does not escape the caller function's
3891	compilation unit.
3892
3893	For more information see
3894	`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html>`)reST";
3895
3896	static const char AttrDoc_LifetimeBound[] = R"reST(The ``lifetimebound`` attribute on a function parameter or implicit object
3897	parameter indicates that objects that are referred to by that parameter may
3898	also be referred to by the return value of the annotated function (or, for a
3899	parameter of a constructor, by the value of the constructed object).
3900
3901	By default, a reference is considered to refer to its referenced object, a
3902	pointer is considered to refer to its pointee, a ``std::initializer_list<T>``
3903	is considered to refer to its underlying array, and aggregates (arrays and
3904	simple ``struct``\s) are considered to refer to all objects that their
3905	transitive subobjects refer to.
3906
3907	Clang warns if it is able to detect that an object or reference refers to
3908	another object with a shorter lifetime. For example, Clang will warn if a
3909	function returns a reference to a local variable, or if a reference is bound to
3910	a temporary object whose lifetime is not extended. By using the
3911	``lifetimebound`` attribute, this determination can be extended to look through
3912	user-declared functions. For example:
3913
3914	.. code-block:: c++
3915
3916	#include <map>
3917	#include <string>
3918
3919	using namespace std::literals;
3920
3921	// Returns m[key] if key is present, or default_value if not.
3922	template<typename T, typename U>
3923	const U &get_or_default(const std::map<T, U> &m [[clang::lifetimebound]],
3924	const T &key, /* note, not lifetimebound */
3925	const U &default_value [[clang::lifetimebound]]) {
3926	if (auto iter = m.find(key); iter != m.end()) return iter->second;
3927	else return default_value;
3928	}
3929
3930	int main() {
3931	std::map<std::string, std::string> m;
3932	// warning: temporary bound to local reference 'val1' will be destroyed
3933	// at the end of the full-expression
3934	const std::string &val1 = get_or_default(m, "foo"s, "bar"s);
3935
3936	// No warning in this case.
3937	std::string def_val = "bar"s;
3938	const std::string &val2 = get_or_default(m, "foo"s, def_val);
3939
3940	return 0;
3941	}
3942
3943	The attribute can be applied to the implicit ``this`` parameter of a member
3944	function by writing the attribute after the function type:
3945
3946	.. code-block:: c++
3947
3948	struct string {
3949	// The returned pointer should not outlive ``*this``.
3950	const char *data() const [[clang::lifetimebound]];
3951	};
3952
3953	This attribute is inspired by the C++ committee paper `P0936R0
3954	<http://wg21.link/p0936r0>`_, but does not affect whether temporary objects
3955	have their lifetimes extended.)reST";
3956
3957	static const char AttrDoc_LifetimeCaptureBy[] = R"reST(Similar to `lifetimebound`_, the ``lifetime_capture_by(X)`` attribute on a
3958	function parameter or implicit object parameter indicates that the capturing
3959	entity ``X`` may refer to the object referred by that parameter.
3960
3961	Below is a list of types of the parameters and what they're considered to refer to:
3962
3963	- A reference param (of non-view type) is considered to refer to its referenced object.
3964	- A pointer param (of non-view type) is considered to refer to its pointee.
3965	- View type param (type annotated with ``[[gsl::Pointer()]]``) is considered to refer
3966	to its pointee (gsl owner). This holds true even if the view type appears as a reference
3967	in the parameter. For example, both ``std::string_view`` and
3968	``const std::string_view &`` are considered to refer to a ``std::string``.
3969	- A ``std::initializer_list<T>`` is considered to refer to its underlying array.
3970	- Aggregates (arrays and simple ``struct``\s) are considered to refer to all
3971	objects that their transitive subobjects refer to.
3972
3973	Clang would diagnose when a temporary object is used as an argument to such an
3974	annotated parameter.
3975	In this case, the capturing entity ``X`` could capture a dangling reference to this
3976	temporary object.
3977
3978	.. code-block:: c++
3979
3980	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
3981	s.insert(a);
3982	}
3983	void use() {
3984	std::set<std::string_view> s;
3985	addToSet(std::string(), s); // Warning: object whose reference is captured by 's' will be destroyed at the end of the full-expression.
3986	// ^^^^^^^^^^^^^
3987	std::string local;
3988	addToSet(local, s); // Ok.
3989	}
3990
3991	The capturing entity ``X`` can be one of the following:
3992
3993	- Another (named) function parameter.
3994
3995	.. code-block:: c++
3996
3997	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
3998	s.insert(a);
3999	}
4000
4001	- ``this`` (in case of member functions).
4002
4003	.. code-block:: c++
4004
4005	class S {
4006	void addToSet(std::string_view a [[clang::lifetime_capture_by(this)]]) {
4007	s.insert(a);
4008	}
4009	std::set<std::string_view> s;
4010	};
4011
4012	Note: When applied to a constructor parameter, `[[clang::lifetime_capture_by(this)]]` is just an alias of `[[clang::lifetimebound]]`.
4013
4014	- `global`, `unknown`.
4015
4016	.. code-block:: c++
4017
4018	std::set<std::string_view> s;
4019	void addToSet(std::string_view a [[clang::lifetime_capture_by(global)]]) {
4020	s.insert(a);
4021	}
4022	void addSomewhere(std::string_view a [[clang::lifetime_capture_by(unknown)]]);
4023
4024	The attribute can be applied to the implicit ``this`` parameter of a member
4025	function by writing the attribute after the function type:
4026
4027	.. code-block:: c++
4028
4029	struct S {
4030	const char data(std::set<S>& s) [[clang::lifetime_capture_by(s)]] {
4031	s.insert(this);
4032	}
4033	};
4034
4035	The attribute supports specifying more than one capturing entities:
4036
4037	.. code-block:: c++
4038
4039	void addToSets(std::string_view a [[clang::lifetime_capture_by(s1, s2)]],
4040	std::set<std::string_view>& s1,
4041	std::set<std::string_view>& s2) {
4042	s1.insert(a);
4043	s2.insert(a);
4044	}
4045
4046	Limitation: The capturing entity ``X`` is not used by the analysis and is
4047	used for documentation purposes only. This is because the analysis is
4048	statement-local and only detects use of a temporary as an argument to the
4049	annotated parameter.
4050
4051	.. code-block:: c++
4052
4053	void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s);
4054	void use() {
4055	std::set<std::string_view> s;
4056	if (foo()) {
4057	std::string str;
4058	addToSet(str, s); // Not detected.
4059	}
4060	})reST";
4061
4062	static const char AttrDoc_Likely[] = R"reST(The ``likely`` and ``unlikely`` attributes are used as compiler hints.
4063	The attributes are used to aid the compiler to determine which branch is
4064	likely or unlikely to be taken. This is done by marking the branch substatement
4065	with one of the two attributes.
4066
4067	It isn't allowed to annotate a single statement with both ``likely`` and
4068	``unlikely``. Annotating the ``true`` and ``false`` branch of an ``if``
4069	statement with the same likelihood attribute will result in a diagnostic and
4070	the attributes are ignored on both branches.
4071
4072	In a ``switch`` statement it's allowed to annotate multiple ``case`` labels
4073	or the ``default`` label with the same likelihood attribute. This makes
4074	* all labels without an attribute have a neutral likelihood,
4075	* all labels marked ``[[likely]]`` have an equally positive likelihood, and
4076	* all labels marked ``[[unlikely]]`` have an equally negative likelihood.
4077	The neutral likelihood is the more likely of path execution than the negative
4078	likelihood. The positive likelihood is the more likely of path of execution
4079	than the neutral likelihood.
4080
4081	These attributes have no effect on the generated code when using
4082	PGO (Profile-Guided Optimization) or at optimization level 0.
4083
4084	In Clang, the attributes will be ignored if they're not placed on
4085	* the ``case`` or ``default`` label of a ``switch`` statement,
4086	* or on the substatement of an ``if`` or ``else`` statement,
4087	* or on the substatement of an ``for`` or ``while`` statement.
4088	The C++ Standard recommends to honor them on every statement in the
4089	path of execution, but that can be confusing:
4090
4091	.. code-block:: c++
4092
4093	if (b) {
4094	[[unlikely]] --b; // In the path of execution,
4095	// this branch is considered unlikely.
4096	}
4097
4098	if (b) {
4099	--b;
4100	if(b)
4101	return;
4102	[[unlikely]] --b; // Not in the path of execution,
4103	} // the branch has no likelihood information.
4104
4105	if (b) {
4106	--b;
4107	foo(b);
4108	// Whether or not the next statement is in the path of execution depends
4109	// on the declaration of foo():
4110	// In the path of execution: void foo(int);
4111	// Not in the path of execution: [[noreturn]] void foo(int);
4112	// This means the likelihood of the branch depends on the declaration
4113	// of foo().
4114	[[unlikely]] --b;
4115	}
4116
4117
4118	Below are some example usages of the likelihood attributes and their effects:
4119
4120	.. code-block:: c++
4121
4122	if (b) [[likely]] { // Placement on the first statement in the branch.
4123	// The compiler will optimize to execute the code here.
4124	} else {
4125	}
4126
4127	if (b)
4128	[[unlikely]] b++; // Placement on the first statement in the branch.
4129	else {
4130	// The compiler will optimize to execute the code here.
4131	}
4132
4133	if (b) {
4134	[[unlikely]] b++; // Placement on the second statement in the branch.
4135	} // The attribute will be ignored.
4136
4137	if (b) [[likely]] {
4138	[[unlikely]] b++; // No contradiction since the second attribute
4139	} // is ignored.
4140
4141	if (b)
4142	;
4143	else [[likely]] {
4144	// The compiler will optimize to execute the code here.
4145	}
4146
4147	if (b)
4148	;
4149	else
4150	// The compiler will optimize to execute the next statement.
4151	[[likely]] b = f();
4152
4153	if (b) [[likely]]; // Both branches are likely. A diagnostic is issued
4154	else [[likely]]; // and the attributes are ignored.
4155
4156	if (b)
4157	[[likely]] int i = 5; // Issues a diagnostic since the attribute
4158	// isn't allowed on a declaration.
4159
4160	switch (i) {
4161	[[likely]] case 1: // This value is likely
4162	...
4163	break;
4164
4165	[[unlikely]] case 2: // This value is unlikely
4166	...
4167	[[fallthrough]];
4168
4169	case 3: // No likelihood attribute
4170	...
4171	[[likely]] break; // No effect
4172
4173	case 4: [[likely]] { // attribute on substatement has no effect
4174	...
4175	break;
4176	}
4177
4178	[[unlikely]] default: // All other values are unlikely
4179	...
4180	break;
4181	}
4182
4183	switch (i) {
4184	[[likely]] case 0: // This value and code path is likely
4185	...
4186	[[fallthrough]];
4187
4188	case 1: // No likelihood attribute, code path is neutral
4189	break; // falling through has no effect on the likelihood
4190
4191	case 2: // No likelihood attribute, code path is neutral
4192	[[fallthrough]];
4193
4194	[[unlikely]] default: // This value and code path are both unlikely
4195	break;
4196	}
4197
4198	for(int i = 0; i != size; ++i) [[likely]] {
4199	... // The loop is the likely path of execution
4200	}
4201
4202	for(const auto &E : Elements) [[likely]] {
4203	... // The loop is the likely path of execution
4204	}
4205
4206	while(i != size) [[unlikely]] {
4207	... // The loop is the unlikely path of execution
4208	} // The generated code will optimize to skip the loop body
4209
4210	while(true) [[unlikely]] {
4211	... // The attribute has no effect
4212	} // Clang elides the comparison and generates an infinite
4213	// loop)reST";
4214
4215	static const char AttrDoc_LoaderUninitialized[] = R"reST(The ``loader_uninitialized`` attribute can be placed on global variables to
4216	indicate that the variable does not need to be zero initialized by the loader.
4217	On most targets, zero-initialization does not incur any additional cost.
4218	For example, most general purpose operating systems deliberately ensure
4219	that all memory is properly initialized in order to avoid leaking privileged
4220	information from the kernel or other programs. However, some targets
4221	do not make this guarantee, and on these targets, avoiding an unnecessary
4222	zero-initialization can have a significant impact on load times and/or code
4223	size.
4224
4225	A declaration with this attribute is a non-tentative definition just as if it
4226	provided an initializer. Variables with this attribute are considered to be
4227	uninitialized in the same sense as a local variable, and the programs must
4228	write to them before reading from them. If the variable's type is a C++ class
4229	type with a non-trivial default constructor, or an array thereof, this attribute
4230	only suppresses the static zero-initialization of the variable, not the dynamic
4231	initialization provided by executing the default constructor.)reST";
4232
4233	static const char AttrDoc_LockReturned[] = R"reST(No documentation.)reST";
4234
4235	static const char AttrDoc_LocksExcluded[] = R"reST(No documentation.)reST";
4236
4237	static const char AttrDoc_LoopHint[] = R"reST(The ``#pragma clang loop`` directive allows loop optimization hints to be
4238	specified for the subsequent loop. The directive allows pipelining to be
4239	disabled, or vectorization, vector predication, interleaving, and unrolling to
4240	be enabled or disabled. Vector width, vector predication, interleave count,
4241	unrolling count, and the initiation interval for pipelining can be explicitly
4242	specified. See `language extensions
4243	<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
4244	for details.)reST";
4245
4246	static const char AttrDoc_M68kInterrupt[] = R"reST(No documentation.)reST";
4247
4248	static const char AttrDoc_M68kRTD[] = R"reST(On M68k targets, this attribute changes the calling convention of a function
4249	to clear parameters off the stack on return. In other words, callee is
4250	responsible for cleaning out the stack space allocated for incoming paramters.
4251	This convention does not support variadic calls or unprototyped functions in C.
4252	When targeting M68010 or newer CPUs, this calling convention is implemented
4253	using the `rtd` instruction.)reST";
4254
4255	static const char AttrDoc_MIGServerRoutine[] = R"reST(The Mach Interface Generator release-on-success convention dictates
4256	functions that follow it to only release arguments passed to them when they
4257	return "success" (a ``kern_return_t`` error code that indicates that
4258	no errors have occurred). Otherwise the release is performed by the MIG client
4259	that called the function. The annotation ``__attribute__((mig_server_routine))``
4260	is applied in order to specify which functions are expected to follow the
4261	convention. This allows the Static Analyzer to find bugs caused by violations of
4262	that convention. The attribute would normally appear on the forward declaration
4263	of the actual server routine in the MIG server header, but it may also be
4264	added to arbitrary functions that need to follow the same convention - for
4265	example, a user can add them to auxiliary functions called by the server routine
4266	that have their return value of type ``kern_return_t`` unconditionally returned
4267	from the routine. The attribute can be applied to C++ methods, and in this case
4268	it will be automatically applied to overrides if the method is virtual. The
4269	attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``.)reST";
4270
4271	static const char AttrDoc_MSABI[] = R"reST(On non-Windows x86_64 and aarch64 targets, this attribute changes the calling convention of
4272	a function to match the default convention used on Windows. This
4273	attribute has no effect on Windows targets or non-x86_64, non-aarch64 targets.)reST";
4274
4275	static const char AttrDoc_MSAllocator[] = R"reST(The ``__declspec(allocator)`` attribute is applied to functions that allocate
4276	memory, such as operator new in C++. When CodeView debug information is emitted
4277	(enabled by ``clang -gcodeview`` or ``clang-cl /Z7``), Clang will attempt to
4278	record the code offset of heap allocation call sites in the debug info. It will
4279	also record the type being allocated using some local heuristics. The Visual
4280	Studio debugger uses this information to `profile memory usage`_.
4281
4282	.. _profile memory usage: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage
4283
4284	This attribute does not affect optimizations in any way, unlike GCC's
4285	``__attribute__((malloc))``.)reST";
4286
4287	static const char AttrDoc_MSConstexpr[] = R"reST(The ``[[msvc::constexpr]]`` attribute can be applied only to a function
4288	definition or a ``return`` statement. It does not impact function declarations.
4289	A ``[[msvc::constexpr]]`` function cannot be ``constexpr`` or ``consteval``.
4290	A ``[[msvc::constexpr]]`` function is treated as if it were a ``constexpr`` function
4291	when it is evaluated in a constant context of ``[[msvc::constexpr]] return`` statement.
4292	Otherwise, it is treated as a regular function.
4293
4294	Semantics of this attribute are enabled only under MSVC compatibility
4295	(``-fms-compatibility-version``) 19.33 and later.)reST";
4296
4297	static const char AttrDoc_MSInheritance[] = R"reST(This collection of keywords is enabled under ``-fms-extensions`` and controls
4298	the pointer-to-member representation used on ``--win32`` targets.
4299
4300	The ``--win32`` targets utilize a pointer-to-member representation which
4301	varies in size and alignment depending on the definition of the underlying
4302	class.
4303
4304	However, this is problematic when a forward declaration is only available and
4305	no definition has been made yet. In such cases, Clang is forced to utilize the
4306	most general representation that is available to it.
4307
4308	These keywords make it possible to use a pointer-to-member representation other
4309	than the most general one regardless of whether or not the definition will ever
4310	be present in the current translation unit.
4311
4312	This family of keywords belong between the ``class-key`` and ``class-name``:
4313
4314	.. code-block:: c++
4315
4316	struct __single_inheritance S;
4317	int S::*i;
4318	struct S {};
4319
4320	This keyword can be applied to class templates but only has an effect when used
4321	on full specializations:
4322
4323	.. code-block:: c++
4324
4325	template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
4326	template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
4327	template <> struct __single_inheritance A<int, float>;
4328
4329	Note that choosing an inheritance model less general than strictly necessary is
4330	an error:
4331
4332	.. code-block:: c++
4333
4334	struct __multiple_inheritance S; // error: inheritance model does not match definition
4335	int S::*i;
4336	struct S {};)reST";
4337
4338	static const char AttrDoc_MSNoVTable[] = R"reST(This attribute can be added to a class declaration or definition to signal to
4339	the compiler that constructors and destructors will not reference the virtual
4340	function table. It is only supported when using the Microsoft C++ ABI.)reST";
4341
4342	static const char AttrDoc_MSP430Interrupt[] = R"reST(No documentation.)reST";
4343
4344	static const char AttrDoc_MSStruct[] = R"reST(The ``ms_struct`` and ``gcc_struct`` attributes request the compiler to enter a
4345	special record layout compatibility mode which mimics the layout of Microsoft or
4346	Itanium C++ ABI respectively. Obviously, if the current C++ ABI matches the
4347	requested ABI, the attribute does nothing. However, if it does not, annotated
4348	structure or class is laid out in a special compatibility mode, which slightly
4349	changes offsets for fields and bit-fields. The intention is to match the layout
4350	of the requested ABI for structures which only use C features.
4351
4352	Note that the default behavior can be controlled by ``-mms-bitfields`` and
4353	``-mno-ms-bitfields`` switches and via ``#pragma ms_struct``.
4354
4355	The primary difference is for bitfields, where the MS variant only packs
4356	adjacent fields into the same allocation unit if they have integral types
4357	of the same size, while the GCC/Itanium variant packs all fields in a bitfield
4358	tightly.)reST";
4359
4360	static const char AttrDoc_MSVtorDisp[] = R"reST()reST";
4361
4362	static const char AttrDoc_MallocSpan[] = R"reST(The ``malloc_span`` attribute can be used to mark that a function which acts
4363	like a system memory allocation function and returns a span-like structure,
4364	where the returned memory range does not alias storage from any other object
4365	accessible to the caller.
4366
4367	In this context, a span-like structure is assumed to have two non-static data
4368	members, one of which is a pointer to the start of the allocated memory and
4369	the other one is either an integer type containing the size of the actually
4370	allocated memory or a pointer to the end of the allocated region. Note, static
4371	data members do not impact whether a type is span-like or not.)reST";
4372
4373	static const char AttrDoc_MaxFieldAlignment[] = R"reST()reST";
4374
4375	static const char AttrDoc_MayAlias[] = R"reST(No documentation.)reST";
4376
4377	static const char AttrDoc_MaybeUndef[] = R"reST(The ``maybe_undef`` attribute can be placed on a function parameter. It indicates
4378	that the parameter is allowed to use undef values. It informs the compiler
4379	to insert a freeze LLVM IR instruction on the function parameter.
4380	Please note that this is an attribute that is used as an internal
4381	implementation detail and not intended to be used by external users.
4382
4383	In languages HIP, CUDA etc., some functions have multi-threaded semantics and
4384	it is enough for only one or some threads to provide defined arguments.
4385	Depending on semantics, undef arguments in some threads don't produce
4386	undefined results in the function call. Since, these functions accept undefined
4387	arguments, ``maybe_undef`` attribute can be placed.
4388
4389	Sample usage:
4390	.. code-block:: c
4391
4392	void maybeundeffunc(int __attribute__((maybe_undef))param);)reST";
4393
4394	static const char AttrDoc_MicroMips[] = R"reST(Clang supports the GNU style ``__attribute__((micromips))`` and
4395	``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
4396	may be attached to a function definition and instructs the backend to generate
4397	or not to generate microMIPS code for that function.
4398
4399	These attributes override the ``-mmicromips`` and ``-mno-micromips`` options
4400	on the command line.)reST";
4401
4402	static const char AttrDoc_MinSize[] = R"reST(This function attribute indicates that optimization passes and code generator passes
4403	make choices that keep the function code size as small as possible. Optimizations may
4404	also sacrifice runtime performance in order to minimize the size of the generated code.)reST";
4405
4406	static const char AttrDoc_MinVectorWidth[] = R"reST(Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This
4407	attribute may be attached to a function and informs the backend that this
4408	function desires vectors of at least this width to be generated. Target-specific
4409	maximum vector widths still apply. This means even if you ask for something
4410	larger than the target supports, you will only get what the target supports.
4411	This attribute is meant to be a hint to control target heuristics that may
4412	generate narrower vectors than what the target hardware supports.
4413
4414	This is currently used by the X86 target to allow some CPUs that support 512-bit
4415	vectors to be limited to using 256-bit vectors to avoid frequency penalties.
4416	This is currently enabled with the ``-prefer-vector-width=256`` command line
4417	option. The ``min_vector_width`` attribute can be used to prevent the backend
4418	from trying to split vector operations to match the ``prefer-vector-width``. All
4419	X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
4420	use of any of the X86-specific vector builtins will implicitly set this
4421	attribute on the calling function. The intent is that explicitly writing vector
4422	code using the X86 intrinsics will prevent ``prefer-vector-width`` from
4423	affecting the code.)reST";
4424
4425	static const char AttrDoc_Mips16[] = R"reST(No documentation.)reST";
4426
4427	static const char AttrDoc_MipsInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on
4428	MIPS targets. This attribute may be attached to a function definition and instructs
4429	the backend to generate appropriate function entry/exit code so that it can be used
4430	directly as an interrupt service routine.
4431
4432	By default, the compiler will produce a function prologue and epilogue suitable for
4433	an interrupt service routine that handles an External Interrupt Controller (eic)
4434	generated interrupt. This behavior can be explicitly requested with the "eic"
4435	argument.
4436
4437	Otherwise, for use with vectored interrupt mode, the argument passed should be
4438	of the form "vector=LEVEL" where LEVEL is one of the following values:
4439	"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
4440	then set the interrupt mask to the corresponding level which will mask all
4441	interrupts up to and including the argument.
4442
4443	The semantics are as follows:
4444
4445	- The prologue is modified so that the Exception Program Counter (EPC) and
4446	Status coprocessor registers are saved to the stack. The interrupt mask is
4447	set so that the function can only be interrupted by a higher priority
4448	interrupt. The epilogue will restore the previous values of EPC and Status.
4449
4450	- The prologue and epilogue are modified to save and restore all non-kernel
4451	registers as necessary.
4452
4453	- The FPU is disabled in the prologue, as the floating pointer registers are not
4454	spilled to the stack.
4455
4456	- The function return sequence is changed to use an exception return instruction.
4457
4458	- The parameter sets the interrupt mask for the function corresponding to the
4459	interrupt level specified. If no mask is specified the interrupt mask
4460	defaults to "eic".)reST";
4461
4462	static const char AttrDoc_MipsLongCall[] = R"reST(Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
4463	and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
4464	only be added to function declarations and change the code generated
4465	by the compiler when directly calling the function. The ``near`` attribute
4466	allows calls to the function to be made using the ``jal`` instruction, which
4467	requires the function to be located in the same naturally aligned 256MB
4468	segment as the caller. The ``long_call`` and ``far`` attributes are synonyms
4469	and require the use of a different call sequence that works regardless
4470	of the distance between the functions.
4471
4472	These attributes have no effect for position-independent code.
4473
4474	These attributes take priority over command line switches such
4475	as ``-mlong-calls`` and ``-mno-long-calls``.)reST";
4476
4477	static const char AttrDoc_MipsShortCall[] = R"reST(Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
4478	``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
4479	on MIPS targets. These attributes may only be added to function declarations
4480	and change the code generated by the compiler when directly calling
4481	the function. The ``short_call`` and ``near`` attributes are synonyms and
4482	allow calls to the function to be made using the ``jal`` instruction, which
4483	requires the function to be located in the same naturally aligned 256MB segment
4484	as the caller. The ``long_call`` and ``far`` attributes are synonyms and
4485	require the use of a different call sequence that works regardless
4486	of the distance between the functions.
4487
4488	These attributes have no effect for position-independent code.
4489
4490	These attributes take priority over command line switches such
4491	as ``-mlong-calls`` and ``-mno-long-calls``.)reST";
4492
4493	static const char AttrDoc_Mode[] = R"reST(No documentation.)reST";
4494
4495	static const char AttrDoc_ModularFormat[] = R"reST(The ``modular_format`` attribute can be applied to a function that bears the
4496	``format`` attribute (or standard library functions) to indicate that the
4497	implementation is "modular", that is, that the implementation is logically
4498	divided into a number of named aspects. When the compiler can determine that
4499	not all aspects of the implementation are needed for a given call, the compiler
4500	may redirect the call to the identifier given as the first argument to the
4501	attribute (the modular implementation function).
4502
4503	The second argument is a implementation name, and the remaining arguments are
4504	aspects of the format string for the compiler to report. The implementation
4505	name is an unevaluated identifier be in the C namespace.
4506
4507	The compiler reports that a call requires an aspect by issuing a relocation for
4508	the symbol ``<impl_name>_<aspect>`` at the point of the call. This arranges for
4509	code and data needed to support the aspect of the implementation to be brought
4510	into the link to satisfy weak references in the modular implemenation function.
4511	If the compiler does not understand an aspect, it must summarily consider any
4512	call to require that aspect.
4513
4514	For example, say ``printf`` is annotated with
4515	``modular_format(__modular_printf, "__printf", "float")``. Then, a call to
4516	``printf(var, 42)`` would be untouched. A call to ``printf("%d", 42)`` would
4517	become a call to ``__modular_printf`` with the same arguments, as would
4518	``printf("%f", 42.0)``. The latter would be accompanied with a strong
4519	relocation against the symbol ``__printf_float``, which would bring floating
4520	point support for ``printf`` into the link.
4521
4522	If the attribute appears more than once on a declaration, or across a chain of
4523	redeclarations, it is an error for the attributes to have different arguments,
4524	excepting that the aspects may be in any order.
4525
4526	The following aspects are currently supported:
4527
4528	- ``float``: The call has a floating point argument)reST";
4529
4530	static const char AttrDoc_MustTail[] = R"reST(If a ``return`` statement is marked ``musttail``, this indicates that the
4531	compiler must generate a tail call for the program to be correct, even when
4532	optimizations are disabled. This guarantees that the call will not cause
4533	unbounded stack growth if it is part of a recursive cycle in the call graph.
4534
4535	If the callee is a virtual function that is implemented by a thunk, there is
4536	no guarantee in general that the thunk tail-calls the implementation of the
4537	virtual function, so such a call in a recursive cycle can still result in
4538	unbounded stack growth.
4539
4540	``clang::musttail`` can only be applied to a ``return`` statement whose value
4541	is the result of a function call (even functions returning void must use
4542	``return``, although no value is returned). The target function must have the
4543	same number of arguments as the caller. The types of the return value and all
4544	arguments must be similar according to C++ rules (differing only in cv
4545	qualifiers or array size), including the implicit "this" argument, if any.
4546	Any variables in scope, including all arguments to the function and the
4547	return value must be trivially destructible. The calling convention of the
4548	caller and callee must match, and they must not be variadic functions or have
4549	old style K&R C function declarations.
4550
4551	The lifetimes of all local variables and function parameters end immediately
4552	before the call to the function. This means that it is undefined behaviour to
4553	pass a pointer or reference to a local variable to the called function, which
4554	is not the case without the attribute. Clang will emit a warning in common
4555	cases where this happens.
4556
4557	``clang::musttail`` provides assurances that the tail call can be optimized on
4558	all targets, not just one.)reST";
4559
4560	static const char AttrDoc_NSConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4561	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4562	convention (e.g. functions starting with "get" are assumed to return at
4563	``+0``).
4564
4565	It can be overridden using a family of the following attributes. In
4566	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4567	a function communicates that the object is returned at ``+1``, and the caller
4568	is responsible for freeing it.
4569	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4570	specifies that the object is returned at ``+0`` and the ownership remains with
4571	the callee.
4572	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4573	the Objective-C method call consumes the reference to ``self``, e.g. by
4574	attaching it to a supplied parameter.
4575	Additionally, parameters can have an annotation
4576	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4577	as that parameter effectively transfers the ownership, and the caller is no
4578	longer responsible for it.
4579	These attributes affect code generation when interacting with ARC code, and
4580	they are used by the Clang Static Analyzer.
4581
4582	In C programs using CoreFoundation, a similar set of attributes:
4583	``__attribute__((cf_returns_not_retained))``,
4584	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4585	have the same respective semantics when applied to CoreFoundation objects.
4586	These attributes affect code generation when interacting with ARC code, and
4587	they are used by the Clang Static Analyzer.
4588
4589	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4590	the same attribute family is present:
4591	``__attribute__((os_returns_not_retained))``,
4592	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4593	with the same respective semantics.
4594	Similar to ``__attribute__((ns_consumes_self))``,
4595	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4596	the reference to "this" (e.g., when attaching it to a different object supplied
4597	as a parameter).
4598	Out parameters (parameters the function is meant to write into,
4599	either via pointers-to-pointers or references-to-pointers)
4600	may be annotated with ``__attribute__((os_returns_retained))``
4601	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4602	written into the out parameter should (or respectively should not) be released
4603	after use.
4604	Since often out parameters may or may not be written depending on the exit
4605	code of the function,
4606	annotations ``__attribute__((os_returns_retained_on_zero))``
4607	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4608	an out parameter at ``+1`` is written if and only if the function returns a zero
4609	(respectively non-zero) error code.
4610	Observe that return-code-dependent out parameter annotations are only
4611	available for retained out parameters, as non-retained object do not have to be
4612	released by the callee.
4613	These attributes are only used by the Clang Static Analyzer.
4614
4615	The family of attributes ``X_returns_X_retained`` can be added to functions,
4616	C++ methods, and Objective-C methods and properties.
4617	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4618	and Objective-C methods.)reST";
4619
4620	static const char AttrDoc_NSConsumesSelf[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4621	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4622	convention (e.g. functions starting with "get" are assumed to return at
4623	``+0``).
4624
4625	It can be overridden using a family of the following attributes. In
4626	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4627	a function communicates that the object is returned at ``+1``, and the caller
4628	is responsible for freeing it.
4629	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4630	specifies that the object is returned at ``+0`` and the ownership remains with
4631	the callee.
4632	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4633	the Objective-C method call consumes the reference to ``self``, e.g. by
4634	attaching it to a supplied parameter.
4635	Additionally, parameters can have an annotation
4636	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4637	as that parameter effectively transfers the ownership, and the caller is no
4638	longer responsible for it.
4639	These attributes affect code generation when interacting with ARC code, and
4640	they are used by the Clang Static Analyzer.
4641
4642	In C programs using CoreFoundation, a similar set of attributes:
4643	``__attribute__((cf_returns_not_retained))``,
4644	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4645	have the same respective semantics when applied to CoreFoundation objects.
4646	These attributes affect code generation when interacting with ARC code, and
4647	they are used by the Clang Static Analyzer.
4648
4649	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4650	the same attribute family is present:
4651	``__attribute__((os_returns_not_retained))``,
4652	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4653	with the same respective semantics.
4654	Similar to ``__attribute__((ns_consumes_self))``,
4655	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4656	the reference to "this" (e.g., when attaching it to a different object supplied
4657	as a parameter).
4658	Out parameters (parameters the function is meant to write into,
4659	either via pointers-to-pointers or references-to-pointers)
4660	may be annotated with ``__attribute__((os_returns_retained))``
4661	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4662	written into the out parameter should (or respectively should not) be released
4663	after use.
4664	Since often out parameters may or may not be written depending on the exit
4665	code of the function,
4666	annotations ``__attribute__((os_returns_retained_on_zero))``
4667	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4668	an out parameter at ``+1`` is written if and only if the function returns a zero
4669	(respectively non-zero) error code.
4670	Observe that return-code-dependent out parameter annotations are only
4671	available for retained out parameters, as non-retained object do not have to be
4672	released by the callee.
4673	These attributes are only used by the Clang Static Analyzer.
4674
4675	The family of attributes ``X_returns_X_retained`` can be added to functions,
4676	C++ methods, and Objective-C methods and properties.
4677	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4678	and Objective-C methods.)reST";
4679
4680	static const char AttrDoc_NSErrorDomain[] = R"reST(In Cocoa frameworks in Objective-C, one can group related error codes in enums
4681	and categorize these enums with error domains.
4682
4683	The ``ns_error_domain`` attribute indicates a global ``NSString`` or
4684	``CFString`` constant representing the error domain that an error code belongs
4685	to. For pointer uniqueness and code size this is a constant symbol, not a
4686	literal.
4687
4688	The domain and error code need to be used together. The ``ns_error_domain``
4689	attribute links error codes to their domain at the source level.
4690
4691	This metadata is useful for documentation purposes, for static analysis, and for
4692	improving interoperability between Objective-C and Swift. It is not used for
4693	code generation in Objective-C.
4694
4695	For example:
4696
4697	.. code-block:: objc
4698
4699	#define NS_ERROR_ENUM(_type, _name, _domain) \
4700	enum _name : _type _name; enum __attribute__((ns_error_domain(_domain))) _name : _type
4701
4702	extern NSString *const MyErrorDomain;
4703	typedef NS_ERROR_ENUM(unsigned char, MyErrorEnum, MyErrorDomain) {
4704	MyErrFirst,
4705	MyErrSecond,
4706	};)reST";
4707
4708	static const char AttrDoc_NSReturnsAutoreleased[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4709	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4710	convention (e.g. functions starting with "get" are assumed to return at
4711	``+0``).
4712
4713	It can be overridden using a family of the following attributes. In
4714	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4715	a function communicates that the object is returned at ``+1``, and the caller
4716	is responsible for freeing it.
4717	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4718	specifies that the object is returned at ``+0`` and the ownership remains with
4719	the callee.
4720	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4721	the Objective-C method call consumes the reference to ``self``, e.g. by
4722	attaching it to a supplied parameter.
4723	Additionally, parameters can have an annotation
4724	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4725	as that parameter effectively transfers the ownership, and the caller is no
4726	longer responsible for it.
4727	These attributes affect code generation when interacting with ARC code, and
4728	they are used by the Clang Static Analyzer.
4729
4730	In C programs using CoreFoundation, a similar set of attributes:
4731	``__attribute__((cf_returns_not_retained))``,
4732	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4733	have the same respective semantics when applied to CoreFoundation objects.
4734	These attributes affect code generation when interacting with ARC code, and
4735	they are used by the Clang Static Analyzer.
4736
4737	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4738	the same attribute family is present:
4739	``__attribute__((os_returns_not_retained))``,
4740	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4741	with the same respective semantics.
4742	Similar to ``__attribute__((ns_consumes_self))``,
4743	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4744	the reference to "this" (e.g., when attaching it to a different object supplied
4745	as a parameter).
4746	Out parameters (parameters the function is meant to write into,
4747	either via pointers-to-pointers or references-to-pointers)
4748	may be annotated with ``__attribute__((os_returns_retained))``
4749	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4750	written into the out parameter should (or respectively should not) be released
4751	after use.
4752	Since often out parameters may or may not be written depending on the exit
4753	code of the function,
4754	annotations ``__attribute__((os_returns_retained_on_zero))``
4755	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4756	an out parameter at ``+1`` is written if and only if the function returns a zero
4757	(respectively non-zero) error code.
4758	Observe that return-code-dependent out parameter annotations are only
4759	available for retained out parameters, as non-retained object do not have to be
4760	released by the callee.
4761	These attributes are only used by the Clang Static Analyzer.
4762
4763	The family of attributes ``X_returns_X_retained`` can be added to functions,
4764	C++ methods, and Objective-C methods and properties.
4765	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4766	and Objective-C methods.)reST";
4767
4768	static const char AttrDoc_NSReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4769	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4770	convention (e.g. functions starting with "get" are assumed to return at
4771	``+0``).
4772
4773	It can be overridden using a family of the following attributes. In
4774	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4775	a function communicates that the object is returned at ``+1``, and the caller
4776	is responsible for freeing it.
4777	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4778	specifies that the object is returned at ``+0`` and the ownership remains with
4779	the callee.
4780	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4781	the Objective-C method call consumes the reference to ``self``, e.g. by
4782	attaching it to a supplied parameter.
4783	Additionally, parameters can have an annotation
4784	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4785	as that parameter effectively transfers the ownership, and the caller is no
4786	longer responsible for it.
4787	These attributes affect code generation when interacting with ARC code, and
4788	they are used by the Clang Static Analyzer.
4789
4790	In C programs using CoreFoundation, a similar set of attributes:
4791	``__attribute__((cf_returns_not_retained))``,
4792	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4793	have the same respective semantics when applied to CoreFoundation objects.
4794	These attributes affect code generation when interacting with ARC code, and
4795	they are used by the Clang Static Analyzer.
4796
4797	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4798	the same attribute family is present:
4799	``__attribute__((os_returns_not_retained))``,
4800	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4801	with the same respective semantics.
4802	Similar to ``__attribute__((ns_consumes_self))``,
4803	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4804	the reference to "this" (e.g., when attaching it to a different object supplied
4805	as a parameter).
4806	Out parameters (parameters the function is meant to write into,
4807	either via pointers-to-pointers or references-to-pointers)
4808	may be annotated with ``__attribute__((os_returns_retained))``
4809	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4810	written into the out parameter should (or respectively should not) be released
4811	after use.
4812	Since often out parameters may or may not be written depending on the exit
4813	code of the function,
4814	annotations ``__attribute__((os_returns_retained_on_zero))``
4815	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4816	an out parameter at ``+1`` is written if and only if the function returns a zero
4817	(respectively non-zero) error code.
4818	Observe that return-code-dependent out parameter annotations are only
4819	available for retained out parameters, as non-retained object do not have to be
4820	released by the callee.
4821	These attributes are only used by the Clang Static Analyzer.
4822
4823	The family of attributes ``X_returns_X_retained`` can be added to functions,
4824	C++ methods, and Objective-C methods and properties.
4825	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4826	and Objective-C methods.)reST";
4827
4828	static const char AttrDoc_NSReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
4829	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
4830	convention (e.g. functions starting with "get" are assumed to return at
4831	``+0``).
4832
4833	It can be overridden using a family of the following attributes. In
4834	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
4835	a function communicates that the object is returned at ``+1``, and the caller
4836	is responsible for freeing it.
4837	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
4838	specifies that the object is returned at ``+0`` and the ownership remains with
4839	the callee.
4840	The annotation ``__attribute__((ns_consumes_self))`` specifies that
4841	the Objective-C method call consumes the reference to ``self``, e.g. by
4842	attaching it to a supplied parameter.
4843	Additionally, parameters can have an annotation
4844	``__attribute__((ns_consumed))``, which specifies that passing an owned object
4845	as that parameter effectively transfers the ownership, and the caller is no
4846	longer responsible for it.
4847	These attributes affect code generation when interacting with ARC code, and
4848	they are used by the Clang Static Analyzer.
4849
4850	In C programs using CoreFoundation, a similar set of attributes:
4851	``__attribute__((cf_returns_not_retained))``,
4852	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
4853	have the same respective semantics when applied to CoreFoundation objects.
4854	These attributes affect code generation when interacting with ARC code, and
4855	they are used by the Clang Static Analyzer.
4856
4857	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
4858	the same attribute family is present:
4859	``__attribute__((os_returns_not_retained))``,
4860	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
4861	with the same respective semantics.
4862	Similar to ``__attribute__((ns_consumes_self))``,
4863	``__attribute__((os_consumes_this))`` specifies that the method call consumes
4864	the reference to "this" (e.g., when attaching it to a different object supplied
4865	as a parameter).
4866	Out parameters (parameters the function is meant to write into,
4867	either via pointers-to-pointers or references-to-pointers)
4868	may be annotated with ``__attribute__((os_returns_retained))``
4869	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
4870	written into the out parameter should (or respectively should not) be released
4871	after use.
4872	Since often out parameters may or may not be written depending on the exit
4873	code of the function,
4874	annotations ``__attribute__((os_returns_retained_on_zero))``
4875	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
4876	an out parameter at ``+1`` is written if and only if the function returns a zero
4877	(respectively non-zero) error code.
4878	Observe that return-code-dependent out parameter annotations are only
4879	available for retained out parameters, as non-retained object do not have to be
4880	released by the callee.
4881	These attributes are only used by the Clang Static Analyzer.
4882
4883	The family of attributes ``X_returns_X_retained`` can be added to functions,
4884	C++ methods, and Objective-C methods and properties.
4885	Attributes ``X_consumed`` can be added to parameters of methods, functions,
4886	and Objective-C methods.)reST";
4887
4888	static const char AttrDoc_Naked[] = R"reST(No documentation.)reST";
4889
4890	static const char AttrDoc_NoAlias[] = R"reST(The ``noalias`` attribute indicates that the only memory accesses inside
4891	function are loads and stores from objects pointed to by its pointer-typed
4892	arguments, with arbitrary offsets.)reST";
4893
4894	static const char AttrDoc_NoBuiltin[] = R"reST(The ``__attribute__((no_builtin))`` is similar to the ``-fno-builtin`` flag
4895	except it is specific to the body of a function. The attribute may also be
4896	applied to a virtual function but has no effect on the behavior of overriding
4897	functions in a derived class.
4898
4899	It accepts one or more strings corresponding to the specific names of the
4900	builtins to disable (e.g. "memcpy", "memset").
4901	If the attribute is used without parameters it will disable all buitins at
4902	once.
4903
4904	.. code-block:: c++
4905
4906	// The compiler is not allowed to add any builtin to foo's body.
4907	void foo(char* data, size_t count) __attribute__((no_builtin)) {
4908	// The compiler is not allowed to convert the loop into
4909	// `__builtin_memset(data, 0xFE, count);`.
4910	for (size_t i = 0; i < count; ++i)
4911	data[i] = 0xFE;
4912	}
4913
4914	// The compiler is not allowed to add the `memcpy` builtin to bar's body.
4915	void bar(char* data, size_t count) __attribute__((no_builtin("memcpy"))) {
4916	// The compiler is allowed to convert the loop into
4917	// `__builtin_memset(data, 0xFE, count);` but cannot generate any
4918	// `__builtin_memcpy`
4919	for (size_t i = 0; i < count; ++i)
4920	data[i] = 0xFE;
4921	})reST";
4922
4923	static const char AttrDoc_NoCommon[] = R"reST(No documentation.)reST";
4924
4925	static const char AttrDoc_NoConvergent[] = R"reST(This attribute prevents a function from being treated as convergent; when a
4926	function is marked ``noconvergent``, calls to that function are not
4927	automatically assumed to be convergent, unless such calls are explicitly marked
4928	as ``convergent``. If a statement is marked as ``noconvergent``, any calls to
4929	inline ``asm`` in that statement are no longer treated as convergent.
4930
4931	In languages following SPMD/SIMT programming model, e.g., CUDA/HIP, function
4932	declarations and inline asm calls are treated as convergent by default for
4933	correctness. This ``noconvergent`` attribute is helpful for developers to
4934	prevent them from being treated as convergent when it's safe.
4935
4936	.. code-block:: c
4937
4938	__device__ float bar(float);
4939	__device__ float foo(float) __attribute__((noconvergent)) {}
4940
4941	__device__ int example(void) {
4942	float x;
4943	[[clang::noconvergent]] x = bar(x); // no effect on convergence
4944	[[clang::noconvergent]] { asm volatile ("nop"); } // the asm call is non-convergent
4945	})reST";
4946
4947	static const char AttrDoc_NoDebug[] = R"reST(The ``nodebug`` attribute allows you to suppress debugging information for a
4948	function or method, for a variable that is not a parameter or a non-static
4949	data member, or for a typedef or using declaration.)reST";
4950
4951	static const char AttrDoc_NoDeref[] = R"reST(The ``noderef`` attribute causes clang to diagnose dereferences of annotated pointer types.
4952	This is ideally used with pointers that point to special memory which cannot be read
4953	from or written to, but allowing for the pointer to be used in pointer arithmetic.
4954	The following are examples of valid expressions where dereferences are diagnosed:
4955
4956	.. code-block:: c
4957
4958	int __attribute__((noderef)) *p;
4959	int x = *p; // warning
4960
4961	int __attribute__((noderef)) **p2;
4962	x = **p2; // warning
4963
4964	int * __attribute__((noderef)) *p3;
4965	p = *p3; // warning
4966
4967	struct S {
4968	int a;
4969	};
4970	struct S __attribute__((noderef)) *s;
4971	x = s->a; // warning
4972	x = (*s).a; // warning
4973
4974	Not all dereferences may diagnose a warning if the value directed by the pointer may not be
4975	accessed. The following are examples of valid expressions where may not be diagnosed:
4976
4977	.. code-block:: c
4978
4979	int *q;
4980	int __attribute__((noderef)) *p;
4981	q = &*p;
4982	q = *&p;
4983
4984	struct S {
4985	int a;
4986	};
4987	struct S __attribute__((noderef)) *s;
4988	p = &s->a;
4989	p = &(*s).a;
4990
4991	``noderef`` is currently only supported for pointers and arrays and not usable
4992	for references or Objective-C object pointers.
4993
4994	.. code-block:: c++
4995
4996	int x = 2;
4997	int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type
4998
4999	.. code-block:: objc
5000
5001	id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type)reST";
5002
5003	static const char AttrDoc_NoDestroy[] = R"reST(The ``no_destroy`` attribute specifies that a variable with static or thread
5004	storage duration shouldn't have its exit-time destructor run. Annotating every
5005	static and thread duration variable with this attribute is equivalent to
5006	invoking clang with -fno-c++-static-destructors.
5007
5008	If a variable is declared with this attribute, clang doesn't access check or
5009	generate the type's destructor. If you have a type that you only want to be
5010	annotated with ``no_destroy``, you can therefore declare the destructor private:
5011
5012	.. code-block:: c++
5013
5014	struct only_no_destroy {
5015	only_no_destroy();
5016	private:
5017	~only_no_destroy();
5018	};
5019
5020	[[clang::no_destroy]] only_no_destroy global; // fine!
5021
5022	Note that destructors are still required for subobjects of aggregates annotated
5023	with this attribute. This is because previously constructed subobjects need to
5024	be destroyed if an exception gets thrown before the initialization of the
5025	complete object is complete. For instance:
5026
5027	.. code-block:: c++
5028
5029	void f() {
5030	try {
5031	[[clang::no_destroy]]
5032	static only_no_destroy array[10]; // error, only_no_destroy has a private destructor.
5033	} catch (...) {
5034	// Handle the error
5035	}
5036	}
5037
5038	Here, if the construction of ``array[9]`` fails with an exception, ``array[0..8]``
5039	will be destroyed, so the element's destructor needs to be accessible.)reST";
5040
5041	static const char AttrDoc_NoDuplicate[] = R"reST(The ``noduplicate`` attribute can be placed on function declarations to control
5042	whether function calls to this function can be duplicated or not as a result of
5043	optimizations. This is required for the implementation of functions with
5044	certain special requirements, like the OpenCL "barrier" function, that might
5045	need to be run concurrently by all the threads that are executing in lockstep
5046	on the hardware. For example this attribute applied on the function
5047	"nodupfunc" in the code below avoids that:
5048
5049	.. code-block:: c
5050
5051	void nodupfunc() __attribute__((noduplicate));
5052	// Setting it as a C++11 attribute is also valid
5053	// void nodupfunc() [[clang::noduplicate]];
5054	void foo();
5055	void bar();
5056
5057	nodupfunc();
5058	if (a > n) {
5059	foo();
5060	} else {
5061	bar();
5062	}
5063
5064	gets possibly modified by some optimizations into code similar to this:
5065
5066	.. code-block:: c
5067
5068	if (a > n) {
5069	nodupfunc();
5070	foo();
5071	} else {
5072	nodupfunc();
5073	bar();
5074	}
5075
5076	where the call to "nodupfunc" is duplicated and sunk into the two branches
5077	of the condition.)reST";
5078
5079	static const char AttrDoc_NoEscape[] = R"reST(``noescape`` placed on a function parameter of a pointer type is used to inform
5080	the compiler that the pointer cannot escape: that is, no reference to the object
5081	the pointer points to that is derived from the parameter value will survive
5082	after the function returns. Users are responsible for making sure parameters
5083	annotated with ``noescape`` do not actually escape. Calling ``free()`` on such
5084	a parameter does not constitute an escape.
5085
5086	For example:
5087
5088	.. code-block:: c
5089
5090	int *gp;
5091
5092	void nonescapingFunc(__attribute__((noescape)) int *p) {
5093	*p += 100; // OK.
5094	}
5095
5096	void escapingFunc(__attribute__((noescape)) int *p) {
5097	gp = p; // Not OK.
5098	}
5099
5100	Additionally, when the parameter is a `block pointer
5101	<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
5102	applies to copies of the block. For example:
5103
5104	.. code-block:: c
5105
5106	typedef void (^BlockTy)();
5107	BlockTy g0, g1;
5108
5109	void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
5110	block(); // OK.
5111	}
5112
5113	void escapingFunc(__attribute__((noescape)) BlockTy block) {
5114	g0 = block; // Not OK.
5115	g1 = Block_copy(block); // Not OK either.
5116	})reST";
5117
5118	static const char AttrDoc_NoInline[] = R"reST(This function attribute suppresses the inlining of a function at the call sites
5119	of the function.
5120
5121	``[[clang::noinline]]`` spelling can be used as a statement attribute; other
5122	spellings of the attribute are not supported on statements. If a statement is
5123	marked ``[[clang::noinline]]`` and contains calls, those calls inside the
5124	statement will not be inlined by the compiler.
5125
5126	``__noinline__`` can be used as a keyword in CUDA/HIP languages. This is to
5127	avoid diagnostics due to usage of ``__attribute__((__noinline__))``
5128	with ``__noinline__`` defined as a macro as ``__attribute__((noinline))``.
5129
5130	.. code-block:: c
5131
5132	int example(void) {
5133	int r;
5134	[[clang::noinline]] foo();
5135	[[clang::noinline]] r = bar();
5136	return r;
5137	})reST";
5138
5139	static const char AttrDoc_NoInstrumentFunction[] = R"reST(No documentation.)reST";
5140
5141	static const char AttrDoc_NoMerge[] = R"reST(If a statement is marked ``nomerge`` and contains call expressions, those call
5142	expressions inside the statement will not be merged during optimization. This
5143	attribute can be used to prevent the optimizer from obscuring the source
5144	location of certain calls. For example, it will prevent tail merging otherwise
5145	identical code sequences that raise an exception or terminate the program. Tail
5146	merging normally reduces the precision of source location information, making
5147	stack traces less useful for debugging. This attribute gives the user control
5148	over the tradeoff between code size and debug information precision.
5149
5150	``nomerge`` attribute can also be used as function attribute to prevent all
5151	calls to the specified function from merging. It has no effect on indirect
5152	calls to such functions. For example:
5153
5154	.. code-block:: c++
5155
5156	[[clang::nomerge]] void foo(int) {}
5157
5158	void bar(int x) {
5159	auto *ptr = foo;
5160	if (x) foo(1); else foo(2); // will not be merged
5161	if (x) ptr(1); else ptr(2); // indirect call, can be merged
5162	}
5163
5164	``nomerge`` attribute can also be used for pointers to functions to
5165	prevent calls through such pointer from merging. In such case the
5166	effect applies only to a specific function pointer. For example:
5167
5168	.. code-block:: c++
5169
5170	[[clang::nomerge]] void (*foo)(int);
5171
5172	void bar(int x) {
5173	auto *ptr = foo;
5174	if (x) foo(1); else foo(2); // will not be merged
5175	if (x) ptr(1); else ptr(2); // 'ptr' has no 'nomerge' attribute, can be merged
5176	})reST";
5177
5178	static const char AttrDoc_NoMicroMips[] = R"reST(Clang supports the GNU style ``__attribute__((micromips))`` and
5179	``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
5180	may be attached to a function definition and instructs the backend to generate
5181	or not to generate microMIPS code for that function.
5182
5183	These attributes override the ``-mmicromips`` and ``-mno-micromips`` options
5184	on the command line.)reST";
5185
5186	static const char AttrDoc_NoMips16[] = R"reST(No documentation.)reST";
5187
5188	static const char AttrDoc_NoProfileFunction[] = R"reST(Use the ``no_profile_instrument_function`` attribute on a function declaration
5189	to denote that the compiler should not instrument the function with
5190	profile-related instrumentation, such as via the
5191	``-fprofile-generate`` / ``-fprofile-instr-generate`` /
5192	``-fcs-profile-generate`` / ``-fprofile-arcs`` flags.)reST";
5193
5194	static const char AttrDoc_NoRandomizeLayout[] = R"reST(The attribute ``randomize_layout``, when attached to a C structure, selects it
5195	for structure layout field randomization; a compile-time hardening technique. A
5196	"seed" value, is specified via the ``-frandomize-layout-seed=`` command line flag.
5197	For example:
5198
5199	.. code-block:: bash
5200
5201	SEED=`od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n'`
5202	make ... CFLAGS="-frandomize-layout-seed=$SEED" ...
5203
5204	You can also supply the seed in a file with ``-frandomize-layout-seed-file=``.
5205	For example:
5206
5207	.. code-block:: bash
5208
5209	od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n' > /tmp/seed_file.txt
5210	make ... CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt" ...
5211
5212	The randomization is deterministic based for a given seed, so the entire
5213	program should be compiled with the same seed, but keep the seed safe
5214	otherwise.
5215
5216	The attribute ``no_randomize_layout``, when attached to a C structure,
5217	instructs the compiler that this structure should not have its field layout
5218	randomized.)reST";
5219
5220	static const char AttrDoc_NoReturn[] = R"reST(No documentation.)reST";
5221
5222	static const char AttrDoc_NoSanitize[] = R"reST(Use the ``no_sanitize`` attribute on a function or a global variable
5223	declaration to specify that a particular instrumentation or set of
5224	instrumentations should not be applied.
5225
5226	The attribute takes a list of string literals with the following accepted
5227	values:
5228
5229	* all values accepted by ``-fno-sanitize=``;
5230	* ``coverage``, to disable SanitizerCoverage instrumentation.
5231
5232	For example, ``__attribute__((no_sanitize("address", "thread")))`` specifies
5233	that AddressSanitizer and ThreadSanitizer should not be applied to the function
5234	or variable. Using ``__attribute__((no_sanitize("coverage")))`` specifies that
5235	SanitizerCoverage should not be applied to the function.
5236
5237	See :ref:`Controlling Code Generation <controlling-code-generation>` for a
5238	full list of supported sanitizer flags.)reST";
5239
5240	static const char AttrDoc_NoSpecializations[] = R"reST(``[[clang::no_specializations]]`` can be applied to function, class, or variable
5241	templates which should not be explicitly specialized by users. This is primarily
5242	used to diagnose user specializations of standard library type traits.)reST";
5243
5244	static const char AttrDoc_NoSpeculativeLoadHardening[] = R"reST(This attribute can be applied to a function declaration in order to indicate
5245	that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
5246	is not needed for the function body. This can also be applied to a method
5247	in Objective C. This attribute will take precedence over the command line flag in
5248	the case where `-mspeculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
5249
5250	Warning: This attribute may not prevent Speculative Load Hardening from being
5251	enabled for a function which inlines a function that has the
5252	'speculative_load_hardening' attribute. This is intended to provide a
5253	maximally conservative model where the code that is marked with the
5254	'speculative_load_hardening' attribute will always (even when inlined)
5255	be hardened. A user of this attribute may want to mark functions called by
5256	a function they do not want to be hardened with the 'noinline' attribute.
5257
5258	For example:
5259
5260	.. code-block:: c
5261
5262	__attribute__((speculative_load_hardening))
5263	int foo(int i) {
5264	return i;
5265	}
5266
5267	// Note: bar() may still have speculative load hardening enabled if
5268	// foo() is inlined into bar(). Mark foo() with __attribute__((noinline))
5269	// to avoid this situation.
5270	__attribute__((no_speculative_load_hardening))
5271	int bar(int i) {
5272	return foo(i);
5273	})reST";
5274
5275	static const char AttrDoc_NoSplitStack[] = R"reST(The ``no_split_stack`` attribute disables the emission of the split stack
5276	preamble for a particular function. It has no effect if ``-fsplit-stack``
5277	is not specified.)reST";
5278
5279	static const char AttrDoc_NoStackProtector[] = R"reST(Clang supports the GNU style ``__attribute__((no_stack_protector))`` and Microsoft
5280	style ``__declspec(safebuffers)`` attribute which disables
5281	the stack protector on the specified function. This attribute is useful for
5282	selectively disabling the stack protector on some functions when building with
5283	``-fstack-protector`` compiler option.
5284
5285	For example, it disables the stack protector for the function ``foo`` but function
5286	``bar`` will still be built with the stack protector with the ``-fstack-protector``
5287	option.
5288
5289	.. code-block:: c
5290
5291	int __attribute__((no_stack_protector))
5292	foo (int x); // stack protection will be disabled for foo.
5293
5294	int bar(int y); // bar can be built with the stack protector.)reST";
5295
5296	static const char AttrDoc_NoThreadSafetyAnalysis[] = R"reST(No documentation.)reST";
5297
5298	static const char AttrDoc_NoThrow[] = R"reST(Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
5299	``__declspec(nothrow)`` attribute as an equivalent of ``noexcept`` on function
5300	declarations. This attribute informs the compiler that the annotated function
5301	does not throw an exception. This prevents exception-unwinding. This attribute
5302	is particularly useful on functions in the C Standard Library that are
5303	guaranteed to not throw an exception.)reST";
5304
5305	static const char AttrDoc_NoTrivialAutoVarInit[] = R"reST(The ``__declspec(no_init_all)`` attribute disables the automatic initialization that the
5306	`-ftrivial-auto-var-init`_ flag would have applied to locals in a marked function, or instances of
5307	a marked type. Note that this attribute has no effect for locals that are automatically initialized
5308	without the `-ftrivial-auto-var-init`_ flag.
5309
5310	.. _`-ftrivial-auto-var-init`: ClangCommandLineReference.html#cmdoption-clang-ftrivial-auto-var-init)reST";
5311
5312	static const char AttrDoc_NoUniqueAddress[] = R"reST(The ``no_unique_address`` attribute allows tail padding in a non-static data
5313	member to overlap other members of the enclosing class (and in the special
5314	case when the type is empty, permits it to fully overlap other members).
5315	The field is laid out as if a base class were encountered at the corresponding
5316	point within the class (except that it does not share a vptr with the enclosing
5317	object).
5318
5319	Example usage:
5320
5321	.. code-block:: c++
5322
5323	template<typename T, typename Alloc> struct my_vector {
5324	T *p;
5325	[[no_unique_address]] Alloc alloc;
5326	// ...
5327	};
5328	static_assert(sizeof(my_vector<int, std::allocator<int>>) == sizeof(int*));
5329
5330	``[[no_unique_address]]`` is a standard C++20 attribute. Clang supports its use
5331	in C++11 onwards.
5332
5333	On MSVC targets, ``[[no_unique_address]]`` is ignored; use
5334	``[[msvc::no_unique_address]]`` instead. Currently there is no guarantee of ABI
5335	compatibility or stability with MSVC.)reST";
5336
5337	static const char AttrDoc_NoUwtable[] = R"reST(Clang supports the ``nouwtable`` attribute which skips emitting
5338	the unwind table entry for the specified function. This attribute is useful for
5339	selectively emitting the unwind table entry on some functions when building with
5340	``-funwind-tables`` compiler option.)reST";
5341
5342	static const char AttrDoc_NonAllocating[] = R"reST(Declares that a function or function type either does or does not allocate heap memory, according
5343	to the optional, compile-time constant boolean argument, which defaults to true. When the argument
5344	is false, the attribute is equivalent to ``allocating``.)reST";
5345
5346	static const char AttrDoc_NonBlocking[] = R"reST(Declares that a function or function type either does or does not block in any way, according
5347	to the optional, compile-time constant boolean argument, which defaults to true. When the argument
5348	is false, the attribute is equivalent to ``blocking``.
5349
5350	For the purposes of diagnostics, ``nonblocking`` is considered to include the
5351	``nonallocating`` guarantee and is therefore a "stronger" constraint or attribute.)reST";
5352
5353	static const char AttrDoc_NonNull[] = R"reST(The ``nonnull`` attribute indicates that some function parameters must not be
5354	null, and can be used in several different ways. It's original usage
5355	(`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_)
5356	is as a function (or Objective-C method) attribute that specifies which
5357	parameters of the function are nonnull in a comma-separated list. For example:
5358
5359	.. code-block:: c
5360
5361	extern void * my_memcpy (void dest, const void src, size_t len)
5362	__attribute__((nonnull (1, 2)));
5363
5364	Here, the ``nonnull`` attribute indicates that parameters 1 and 2
5365	cannot have a null value. Omitting the parenthesized list of parameter indices
5366	means that all parameters of pointer type cannot be null:
5367
5368	.. code-block:: c
5369
5370	extern void * my_memcpy (void dest, const void src, size_t len)
5371	__attribute__((nonnull));
5372
5373	Clang also allows the ``nonnull`` attribute to be placed directly on a function
5374	(or Objective-C method) parameter, eliminating the need to specify the
5375	parameter index ahead of type. For example:
5376
5377	.. code-block:: c
5378
5379	extern void * my_memcpy (void *dest __attribute__((nonnull)),
5380	const void *src __attribute__((nonnull)), size_t len);
5381
5382	Note that the ``nonnull`` attribute indicates that passing null to a non-null
5383	parameter is undefined behavior, which the optimizer may take advantage of to,
5384	e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a
5385	pointer cannot be null in a more general manner (because it is part of the type
5386	system) and does not imply undefined behavior, making it more widely applicable.)reST";
5387
5388	static const char AttrDoc_NonString[] = R"reST(The ``nonstring`` attribute can be applied to the declaration of a variable or
5389	a field whose type is a character pointer or character array to specify that
5390	the buffer is not intended to behave like a null-terminated string. This will
5391	silence diagnostics with code like:
5392
5393	.. code-block:: c
5394
5395	char BadStr[3] = "foo"; // No space for the null terminator, diagnosed
5396	__attribute__((nonstring)) char NotAStr[3] = "foo"; // Not diagnosed)reST";
5397
5398	static const char AttrDoc_NotTailCalled[] = R"reST(The ``not_tail_called`` attribute prevents tail-call optimization on statically
5399	bound calls. Objective-c methods, and functions marked as ``always_inline``
5400	cannot be marked as ``not_tail_called``.
5401
5402	For example, it prevents tail-call optimization in the following case:
5403
5404	.. code-block:: c
5405
5406	int __attribute__((not_tail_called)) foo1(int);
5407
5408	int foo2(int a) {
5409	return foo1(a); // No tail-call optimization on direct calls.
5410	}
5411
5412	However, it doesn't prevent tail-call optimization in this case:
5413
5414	.. code-block:: c
5415
5416	int __attribute__((not_tail_called)) foo1(int);
5417
5418	int foo2(int a) {
5419	int (*fn)(int) = &foo1;
5420
5421	// not_tail_called has no effect on an indirect call even if the call can
5422	// be resolved at compile time.
5423	return (*fn)(a);
5424	}
5425
5426	Generally, marking an overriding virtual function as ``not_tail_called`` is
5427	not useful, because this attribute is a property of the static type. Calls
5428	made through a pointer or reference to the base class type will respect
5429	the ``not_tail_called`` attribute of the base class's member function,
5430	regardless of the runtime destination of the call:
5431
5432	.. code-block:: c++
5433
5434	struct Foo { virtual void f(); };
5435	struct Bar : Foo {
5436	[[clang::not_tail_called]] void f() override;
5437	};
5438	void callera(Bar& bar) {
5439	Foo& foo = bar;
5440	// not_tail_called has no effect on here, even though the
5441	// underlying method is f from Bar.
5442	foo.f();
5443	bar.f(); // No tail-call optimization on here.
5444	})reST";
5445
5446	static const char AttrDoc_OMPAllocateDecl[] = R"reST()reST";
5447
5448	static const char AttrDoc_OMPAssume[] = R"reST(Clang supports the ``[[omp::assume("assumption")]]`` attribute to
5449	provide additional information to the optimizer. The string-literal, here
5450	"assumption", will be attached to the function declaration such that later
5451	analysis and optimization passes can assume the "assumption" to hold.
5452	This is similar to :ref:`__builtin_assume <langext-__builtin_assume>` but
5453	instead of an expression that can be assumed to be non-zero, the assumption is
5454	expressed as a string and it holds for the entire function.
5455
5456	A function can have multiple assume attributes and they propagate from prior
5457	declarations to later definitions. Multiple assumptions are aggregated into a
5458	single comma separated string. Thus, one can provide multiple assumptions via
5459	a comma separated string, i.a.,
5460	``[[omp::assume("assumption1,assumption2")]]``.
5461
5462	While LLVM plugins might provide more assumption strings, the default LLVM
5463	optimization passes are aware of the following assumptions:
5464
5465	.. code-block:: none
5466
5467	"omp_no_openmp"
5468	"omp_no_openmp_routines"
5469	"omp_no_parallelism"
5470	"omp_no_openmp_constructs"
5471
5472	The OpenMP standard defines the meaning of OpenMP assumptions ("omp_XYZ" is
5473	spelled "XYZ" in the `OpenMP 5.1 Standard`_).
5474
5475	.. _`OpenMP 5.1 Standard`: https://www.openmp.org/spec-html/5.1/openmpsu37.html#x56-560002.5.2)reST";
5476
5477	static const char AttrDoc_OMPCaptureKind[] = R"reST()reST";
5478
5479	static const char AttrDoc_OMPCaptureNoInit[] = R"reST()reST";
5480
5481	static const char AttrDoc_OMPDeclareSimdDecl[] = R"reST(The ``declare simd`` construct can be applied to a function to enable the creation
5482	of one or more versions that can process multiple arguments using SIMD
5483	instructions from a single invocation in a SIMD loop. The ``declare simd``
5484	directive is a declarative directive. There may be multiple ``declare simd``
5485	directives for a function. The use of a ``declare simd`` construct on a function
5486	enables the creation of SIMD versions of the associated function that can be
5487	used to process multiple arguments from a single invocation from a SIMD loop
5488	concurrently.
5489	The syntax of the ``declare simd`` construct is as follows:
5490
5491	.. code-block:: none
5492
5493	#pragma omp declare simd [clause[[,] clause] ...] new-line
5494	[#pragma omp declare simd [clause[[,] clause] ...] new-line]
5495	[...]
5496	function definition or declaration
5497
5498	where clause is one of the following:
5499
5500	.. code-block:: none
5501
5502	simdlen(length)
5503	linear(argument-list[:constant-linear-step])
5504	aligned(argument-list[:alignment])
5505	uniform(argument-list)
5506	inbranch
5507	notinbranch)reST";
5508
5509	static const char AttrDoc_OMPDeclareTargetDecl[] = R"reST(The ``declare target`` directive specifies that variables and functions are mapped
5510	to a device for OpenMP offload mechanism.
5511
5512	The syntax of the declare target directive is as follows:
5513
5514	.. code-block:: c
5515
5516	#pragma omp declare target new-line
5517	declarations-definition-seq
5518	#pragma omp end declare target new-line
5519
5520	or
5521
5522	.. code-block:: c
5523
5524	#pragma omp declare target (extended-list) new-line
5525
5526	or
5527
5528	.. code-block:: c
5529
5530	#pragma omp declare target clause[ [,] clause ... ] new-line
5531
5532	where clause is one of the following:
5533
5534
5535	.. code-block:: c
5536
5537	to(extended-list)
5538	link(list)
5539	device_type(host \| nohost \| any))reST";
5540
5541	static const char AttrDoc_OMPDeclareVariant[] = R"reST(The ``declare variant`` directive declares a specialized variant of a base
5542	function and specifies the context in which that specialized variant is used.
5543	The declare variant directive is a declarative directive.
5544	The syntax of the ``declare variant`` construct is as follows:
5545
5546	.. code-block:: none
5547
5548	#pragma omp declare variant(variant-func-id) clause new-line
5549	[#pragma omp declare variant(variant-func-id) clause new-line]
5550	[...]
5551	function definition or declaration
5552
5553	where clause is one of the following:
5554
5555	.. code-block:: none
5556
5557	match(context-selector-specification)
5558
5559	and where ``variant-func-id`` is the name of a function variant that is either a
5560	base language identifier or, for C++, a template-id.
5561
5562	Clang provides the following context selector extensions, used via
5563	``implementation={extension(EXTENSION)}``:
5564
5565	.. code-block:: none
5566
5567	match_all
5568	match_any
5569	match_none
5570	disable_implicit_base
5571	allow_templates
5572	bind_to_declaration
5573
5574	The match extensions change when the entire context selector is considered a
5575	match for an OpenMP context. The default is ``all``, with ``none`` no trait in the
5576	selector is allowed to be in the OpenMP context, with ``any`` a single trait in
5577	both the selector and OpenMP context is sufficient. Only a single match
5578	extension trait is allowed per context selector.
5579	The disable extensions remove default effects of the ``begin declare variant``
5580	applied to a definition. If ``disable_implicit_base`` is given, we will not
5581	introduce an implicit base function for a variant if no base function was
5582	found. The variant is still generated but will never be called, due to the
5583	absence of a base function and consequently calls to a base function.
5584	The allow extensions change when the ``begin declare variant`` effect is
5585	applied to a definition. If ``allow_templates`` is given, template function
5586	definitions are considered as specializations of existing or assumed template
5587	declarations with the same name. The template parameters for the base functions
5588	are used to instantiate the specialization. If ``bind_to_declaration`` is given,
5589	apply the same variant rules to function declarations. This allows the user to
5590	override declarations with only a function declaration.)reST";
5591
5592	static const char AttrDoc_OMPGroupPrivateDecl[] = R"reST()reST";
5593
5594	static const char AttrDoc_OMPReferencedVar[] = R"reST()reST";
5595
5596	static const char AttrDoc_OMPThreadPrivateDecl[] = R"reST()reST";
5597
5598	static const char AttrDoc_OSConsumed[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5599	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5600	convention (e.g. functions starting with "get" are assumed to return at
5601	``+0``).
5602
5603	It can be overridden using a family of the following attributes. In
5604	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5605	a function communicates that the object is returned at ``+1``, and the caller
5606	is responsible for freeing it.
5607	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5608	specifies that the object is returned at ``+0`` and the ownership remains with
5609	the callee.
5610	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5611	the Objective-C method call consumes the reference to ``self``, e.g. by
5612	attaching it to a supplied parameter.
5613	Additionally, parameters can have an annotation
5614	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5615	as that parameter effectively transfers the ownership, and the caller is no
5616	longer responsible for it.
5617	These attributes affect code generation when interacting with ARC code, and
5618	they are used by the Clang Static Analyzer.
5619
5620	In C programs using CoreFoundation, a similar set of attributes:
5621	``__attribute__((cf_returns_not_retained))``,
5622	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5623	have the same respective semantics when applied to CoreFoundation objects.
5624	These attributes affect code generation when interacting with ARC code, and
5625	they are used by the Clang Static Analyzer.
5626
5627	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5628	the same attribute family is present:
5629	``__attribute__((os_returns_not_retained))``,
5630	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5631	with the same respective semantics.
5632	Similar to ``__attribute__((ns_consumes_self))``,
5633	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5634	the reference to "this" (e.g., when attaching it to a different object supplied
5635	as a parameter).
5636	Out parameters (parameters the function is meant to write into,
5637	either via pointers-to-pointers or references-to-pointers)
5638	may be annotated with ``__attribute__((os_returns_retained))``
5639	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5640	written into the out parameter should (or respectively should not) be released
5641	after use.
5642	Since often out parameters may or may not be written depending on the exit
5643	code of the function,
5644	annotations ``__attribute__((os_returns_retained_on_zero))``
5645	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5646	an out parameter at ``+1`` is written if and only if the function returns a zero
5647	(respectively non-zero) error code.
5648	Observe that return-code-dependent out parameter annotations are only
5649	available for retained out parameters, as non-retained object do not have to be
5650	released by the callee.
5651	These attributes are only used by the Clang Static Analyzer.
5652
5653	The family of attributes ``X_returns_X_retained`` can be added to functions,
5654	C++ methods, and Objective-C methods and properties.
5655	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5656	and Objective-C methods.)reST";
5657
5658	static const char AttrDoc_OSConsumesThis[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5659	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5660	convention (e.g. functions starting with "get" are assumed to return at
5661	``+0``).
5662
5663	It can be overridden using a family of the following attributes. In
5664	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5665	a function communicates that the object is returned at ``+1``, and the caller
5666	is responsible for freeing it.
5667	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5668	specifies that the object is returned at ``+0`` and the ownership remains with
5669	the callee.
5670	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5671	the Objective-C method call consumes the reference to ``self``, e.g. by
5672	attaching it to a supplied parameter.
5673	Additionally, parameters can have an annotation
5674	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5675	as that parameter effectively transfers the ownership, and the caller is no
5676	longer responsible for it.
5677	These attributes affect code generation when interacting with ARC code, and
5678	they are used by the Clang Static Analyzer.
5679
5680	In C programs using CoreFoundation, a similar set of attributes:
5681	``__attribute__((cf_returns_not_retained))``,
5682	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5683	have the same respective semantics when applied to CoreFoundation objects.
5684	These attributes affect code generation when interacting with ARC code, and
5685	they are used by the Clang Static Analyzer.
5686
5687	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5688	the same attribute family is present:
5689	``__attribute__((os_returns_not_retained))``,
5690	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5691	with the same respective semantics.
5692	Similar to ``__attribute__((ns_consumes_self))``,
5693	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5694	the reference to "this" (e.g., when attaching it to a different object supplied
5695	as a parameter).
5696	Out parameters (parameters the function is meant to write into,
5697	either via pointers-to-pointers or references-to-pointers)
5698	may be annotated with ``__attribute__((os_returns_retained))``
5699	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5700	written into the out parameter should (or respectively should not) be released
5701	after use.
5702	Since often out parameters may or may not be written depending on the exit
5703	code of the function,
5704	annotations ``__attribute__((os_returns_retained_on_zero))``
5705	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5706	an out parameter at ``+1`` is written if and only if the function returns a zero
5707	(respectively non-zero) error code.
5708	Observe that return-code-dependent out parameter annotations are only
5709	available for retained out parameters, as non-retained object do not have to be
5710	released by the callee.
5711	These attributes are only used by the Clang Static Analyzer.
5712
5713	The family of attributes ``X_returns_X_retained`` can be added to functions,
5714	C++ methods, and Objective-C methods and properties.
5715	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5716	and Objective-C methods.)reST";
5717
5718	static const char AttrDoc_OSReturnsNotRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5719	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5720	convention (e.g. functions starting with "get" are assumed to return at
5721	``+0``).
5722
5723	It can be overridden using a family of the following attributes. In
5724	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5725	a function communicates that the object is returned at ``+1``, and the caller
5726	is responsible for freeing it.
5727	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5728	specifies that the object is returned at ``+0`` and the ownership remains with
5729	the callee.
5730	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5731	the Objective-C method call consumes the reference to ``self``, e.g. by
5732	attaching it to a supplied parameter.
5733	Additionally, parameters can have an annotation
5734	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5735	as that parameter effectively transfers the ownership, and the caller is no
5736	longer responsible for it.
5737	These attributes affect code generation when interacting with ARC code, and
5738	they are used by the Clang Static Analyzer.
5739
5740	In C programs using CoreFoundation, a similar set of attributes:
5741	``__attribute__((cf_returns_not_retained))``,
5742	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5743	have the same respective semantics when applied to CoreFoundation objects.
5744	These attributes affect code generation when interacting with ARC code, and
5745	they are used by the Clang Static Analyzer.
5746
5747	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5748	the same attribute family is present:
5749	``__attribute__((os_returns_not_retained))``,
5750	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5751	with the same respective semantics.
5752	Similar to ``__attribute__((ns_consumes_self))``,
5753	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5754	the reference to "this" (e.g., when attaching it to a different object supplied
5755	as a parameter).
5756	Out parameters (parameters the function is meant to write into,
5757	either via pointers-to-pointers or references-to-pointers)
5758	may be annotated with ``__attribute__((os_returns_retained))``
5759	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5760	written into the out parameter should (or respectively should not) be released
5761	after use.
5762	Since often out parameters may or may not be written depending on the exit
5763	code of the function,
5764	annotations ``__attribute__((os_returns_retained_on_zero))``
5765	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5766	an out parameter at ``+1`` is written if and only if the function returns a zero
5767	(respectively non-zero) error code.
5768	Observe that return-code-dependent out parameter annotations are only
5769	available for retained out parameters, as non-retained object do not have to be
5770	released by the callee.
5771	These attributes are only used by the Clang Static Analyzer.
5772
5773	The family of attributes ``X_returns_X_retained`` can be added to functions,
5774	C++ methods, and Objective-C methods and properties.
5775	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5776	and Objective-C methods.)reST";
5777
5778	static const char AttrDoc_OSReturnsRetained[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5779	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5780	convention (e.g. functions starting with "get" are assumed to return at
5781	``+0``).
5782
5783	It can be overridden using a family of the following attributes. In
5784	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5785	a function communicates that the object is returned at ``+1``, and the caller
5786	is responsible for freeing it.
5787	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5788	specifies that the object is returned at ``+0`` and the ownership remains with
5789	the callee.
5790	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5791	the Objective-C method call consumes the reference to ``self``, e.g. by
5792	attaching it to a supplied parameter.
5793	Additionally, parameters can have an annotation
5794	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5795	as that parameter effectively transfers the ownership, and the caller is no
5796	longer responsible for it.
5797	These attributes affect code generation when interacting with ARC code, and
5798	they are used by the Clang Static Analyzer.
5799
5800	In C programs using CoreFoundation, a similar set of attributes:
5801	``__attribute__((cf_returns_not_retained))``,
5802	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5803	have the same respective semantics when applied to CoreFoundation objects.
5804	These attributes affect code generation when interacting with ARC code, and
5805	they are used by the Clang Static Analyzer.
5806
5807	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5808	the same attribute family is present:
5809	``__attribute__((os_returns_not_retained))``,
5810	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5811	with the same respective semantics.
5812	Similar to ``__attribute__((ns_consumes_self))``,
5813	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5814	the reference to "this" (e.g., when attaching it to a different object supplied
5815	as a parameter).
5816	Out parameters (parameters the function is meant to write into,
5817	either via pointers-to-pointers or references-to-pointers)
5818	may be annotated with ``__attribute__((os_returns_retained))``
5819	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5820	written into the out parameter should (or respectively should not) be released
5821	after use.
5822	Since often out parameters may or may not be written depending on the exit
5823	code of the function,
5824	annotations ``__attribute__((os_returns_retained_on_zero))``
5825	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5826	an out parameter at ``+1`` is written if and only if the function returns a zero
5827	(respectively non-zero) error code.
5828	Observe that return-code-dependent out parameter annotations are only
5829	available for retained out parameters, as non-retained object do not have to be
5830	released by the callee.
5831	These attributes are only used by the Clang Static Analyzer.
5832
5833	The family of attributes ``X_returns_X_retained`` can be added to functions,
5834	C++ methods, and Objective-C methods and properties.
5835	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5836	and Objective-C methods.)reST";
5837
5838	static const char AttrDoc_OSReturnsRetainedOnNonZero[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5839	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5840	convention (e.g. functions starting with "get" are assumed to return at
5841	``+0``).
5842
5843	It can be overridden using a family of the following attributes. In
5844	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5845	a function communicates that the object is returned at ``+1``, and the caller
5846	is responsible for freeing it.
5847	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5848	specifies that the object is returned at ``+0`` and the ownership remains with
5849	the callee.
5850	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5851	the Objective-C method call consumes the reference to ``self``, e.g. by
5852	attaching it to a supplied parameter.
5853	Additionally, parameters can have an annotation
5854	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5855	as that parameter effectively transfers the ownership, and the caller is no
5856	longer responsible for it.
5857	These attributes affect code generation when interacting with ARC code, and
5858	they are used by the Clang Static Analyzer.
5859
5860	In C programs using CoreFoundation, a similar set of attributes:
5861	``__attribute__((cf_returns_not_retained))``,
5862	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5863	have the same respective semantics when applied to CoreFoundation objects.
5864	These attributes affect code generation when interacting with ARC code, and
5865	they are used by the Clang Static Analyzer.
5866
5867	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5868	the same attribute family is present:
5869	``__attribute__((os_returns_not_retained))``,
5870	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5871	with the same respective semantics.
5872	Similar to ``__attribute__((ns_consumes_self))``,
5873	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5874	the reference to "this" (e.g., when attaching it to a different object supplied
5875	as a parameter).
5876	Out parameters (parameters the function is meant to write into,
5877	either via pointers-to-pointers or references-to-pointers)
5878	may be annotated with ``__attribute__((os_returns_retained))``
5879	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5880	written into the out parameter should (or respectively should not) be released
5881	after use.
5882	Since often out parameters may or may not be written depending on the exit
5883	code of the function,
5884	annotations ``__attribute__((os_returns_retained_on_zero))``
5885	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5886	an out parameter at ``+1`` is written if and only if the function returns a zero
5887	(respectively non-zero) error code.
5888	Observe that return-code-dependent out parameter annotations are only
5889	available for retained out parameters, as non-retained object do not have to be
5890	released by the callee.
5891	These attributes are only used by the Clang Static Analyzer.
5892
5893	The family of attributes ``X_returns_X_retained`` can be added to functions,
5894	C++ methods, and Objective-C methods and properties.
5895	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5896	and Objective-C methods.)reST";
5897
5898	static const char AttrDoc_OSReturnsRetainedOnZero[] = R"reST(The behavior of a function with respect to reference counting for Foundation
5899	(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
5900	convention (e.g. functions starting with "get" are assumed to return at
5901	``+0``).
5902
5903	It can be overridden using a family of the following attributes. In
5904	Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
5905	a function communicates that the object is returned at ``+1``, and the caller
5906	is responsible for freeing it.
5907	Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
5908	specifies that the object is returned at ``+0`` and the ownership remains with
5909	the callee.
5910	The annotation ``__attribute__((ns_consumes_self))`` specifies that
5911	the Objective-C method call consumes the reference to ``self``, e.g. by
5912	attaching it to a supplied parameter.
5913	Additionally, parameters can have an annotation
5914	``__attribute__((ns_consumed))``, which specifies that passing an owned object
5915	as that parameter effectively transfers the ownership, and the caller is no
5916	longer responsible for it.
5917	These attributes affect code generation when interacting with ARC code, and
5918	they are used by the Clang Static Analyzer.
5919
5920	In C programs using CoreFoundation, a similar set of attributes:
5921	``__attribute__((cf_returns_not_retained))``,
5922	``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
5923	have the same respective semantics when applied to CoreFoundation objects.
5924	These attributes affect code generation when interacting with ARC code, and
5925	they are used by the Clang Static Analyzer.
5926
5927	Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
5928	the same attribute family is present:
5929	``__attribute__((os_returns_not_retained))``,
5930	``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
5931	with the same respective semantics.
5932	Similar to ``__attribute__((ns_consumes_self))``,
5933	``__attribute__((os_consumes_this))`` specifies that the method call consumes
5934	the reference to "this" (e.g., when attaching it to a different object supplied
5935	as a parameter).
5936	Out parameters (parameters the function is meant to write into,
5937	either via pointers-to-pointers or references-to-pointers)
5938	may be annotated with ``__attribute__((os_returns_retained))``
5939	or ``__attribute__((os_returns_not_retained))`` which specifies that the object
5940	written into the out parameter should (or respectively should not) be released
5941	after use.
5942	Since often out parameters may or may not be written depending on the exit
5943	code of the function,
5944	annotations ``__attribute__((os_returns_retained_on_zero))``
5945	and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
5946	an out parameter at ``+1`` is written if and only if the function returns a zero
5947	(respectively non-zero) error code.
5948	Observe that return-code-dependent out parameter annotations are only
5949	available for retained out parameters, as non-retained object do not have to be
5950	released by the callee.
5951	These attributes are only used by the Clang Static Analyzer.
5952
5953	The family of attributes ``X_returns_X_retained`` can be added to functions,
5954	C++ methods, and Objective-C methods and properties.
5955	Attributes ``X_consumed`` can be added to parameters of methods, functions,
5956	and Objective-C methods.)reST";
5957
5958	static const char AttrDoc_ObjCBoxable[] = R"reST(Structs and unions marked with the ``objc_boxable`` attribute can be used
5959	with the Objective-C boxed expression syntax, ``@(...)``.
5960
5961	Usage: ``__attribute__((objc_boxable))``. This attribute
5962	can only be placed on a declaration of a trivially-copyable struct or union:
5963
5964	.. code-block:: objc
5965
5966	struct __attribute__((objc_boxable)) some_struct {
5967	int i;
5968	};
5969	union __attribute__((objc_boxable)) some_union {
5970	int i;
5971	float f;
5972	};
5973	typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
5974
5975	// ...
5976
5977	some_struct ss;
5978	NSValue *boxed = @(ss);)reST";
5979
5980	static const char AttrDoc_ObjCBridge[] = R"reST(No documentation.)reST";
5981
5982	static const char AttrDoc_ObjCBridgeMutable[] = R"reST(No documentation.)reST";
5983
5984	static const char AttrDoc_ObjCBridgeRelated[] = R"reST(No documentation.)reST";
5985
5986	static const char AttrDoc_ObjCClassStub[] = R"reST(This attribute specifies that the Objective-C class to which it applies is
5987	instantiated at runtime.
5988
5989	Unlike ``__attribute__((objc_runtime_visible))``, a class having this attribute
5990	still has a "class stub" that is visible to the linker. This allows categories
5991	to be defined. Static message sends with the class as a receiver use a special
5992	access pattern to ensure the class is lazily instantiated from the class stub.
5993
5994	Classes annotated with this attribute cannot be subclassed and cannot have
5995	implementations defined for them. This attribute is intended for use in
5996	Swift-generated headers for classes defined in Swift.
5997
5998	Adding or removing this attribute to a class is an ABI-breaking change.)reST";
5999
6000	static const char AttrDoc_ObjCDesignatedInitializer[] = R"reST(No documentation.)reST";
6001
6002	static const char AttrDoc_ObjCDirect[] = R"reST(The ``objc_direct`` attribute can be used to mark an Objective-C method as
6003	being direct. A direct method is treated statically like an ordinary method,
6004	but dynamically it behaves more like a C function. This lowers some of the costs
6005	associated with the method but also sacrifices some of the ordinary capabilities
6006	of Objective-C methods.
6007
6008	A message send of a direct method calls the implementation directly, as if it
6009	were a C function, rather than using ordinary Objective-C method dispatch. This
6010	is substantially faster and potentially allows the implementation to be inlined,
6011	but it also means the method cannot be overridden in subclasses or replaced
6012	dynamically, as ordinary Objective-C methods can.
6013
6014	Furthermore, a direct method is not listed in the class's method lists. This
6015	substantially reduces the code-size overhead of the method but also means it
6016	cannot be called dynamically using ordinary Objective-C method dispatch at all;
6017	in particular, this means that it cannot override a superclass method or satisfy
6018	a protocol requirement.
6019
6020	Because a direct method cannot be overridden, it is an error to perform
6021	a ``super`` message send of one.
6022
6023	Although a message send of a direct method causes the method to be called
6024	directly as if it were a C function, it still obeys Objective-C semantics in other
6025	ways:
6026
6027	- If the receiver is ``nil``, the message send does nothing and returns the zero value
6028	for the return type.
6029
6030	- A message send of a direct class method will cause the class to be initialized,
6031	including calling the ``+initialize`` method if present.
6032
6033	- The implicit ``_cmd`` parameter containing the method's selector is still defined.
6034	In order to minimize code-size costs, the implementation will not emit a reference
6035	to the selector if the parameter is unused within the method.
6036
6037	Symbols for direct method implementations are implicitly given hidden
6038	visibility, meaning that they can only be called within the same linkage unit.
6039
6040	It is an error to do any of the following:
6041
6042	- declare a direct method in a protocol,
6043	- declare an override of a direct method with a method in a subclass,
6044	- declare an override of a non-direct method with a direct method in a subclass,
6045	- declare a method with different directness in different class interfaces, or
6046	- implement a non-direct method (as declared in any class interface) with a direct method.
6047
6048	If any of these rules would be violated if every method defined in an
6049	``@implementation`` within a single linkage unit were declared in an
6050	appropriate class interface, the program is ill-formed with no diagnostic
6051	required. If a violation of this rule is not diagnosed, behavior remains
6052	well-defined; this paragraph is simply reserving the right to diagnose such
6053	conflicts in the future, not to treat them as undefined behavior.
6054
6055	Additionally, Clang will warn about any ``@selector`` expression that
6056	names a selector that is only known to be used for direct methods.
6057
6058	For the purpose of these rules, a "class interface" includes a class's primary
6059	``@interface`` block, its class extensions, its categories, its declared protocols,
6060	and all the class interfaces of its superclasses.
6061
6062	An Objective-C property can be declared with the ``direct`` property
6063	attribute. If a direct property declaration causes an implicit declaration of
6064	a getter or setter method (that is, if the given method is not explicitly
6065	declared elsewhere), the method is declared to be direct.
6066
6067	Some programmers may wish to make many methods direct at once. In order
6068	to simplify this, the ``objc_direct_members`` attribute is provided; see its
6069	documentation for more information.)reST";
6070
6071	static const char AttrDoc_ObjCDirectMembers[] = R"reST(The ``objc_direct_members`` attribute can be placed on an Objective-C
6072	``@interface`` or ``@implementation`` to mark that methods declared
6073	therein should be considered direct by default. See the documentation
6074	for ``objc_direct`` for more information about direct methods.
6075
6076	When ``objc_direct_members`` is placed on an ``@interface`` block, every
6077	method in the block is considered to be declared as direct. This includes any
6078	implicit method declarations introduced by property declarations. If the method
6079	redeclares a non-direct method, the declaration is ill-formed, exactly as if the
6080	method was annotated with the ``objc_direct`` attribute.
6081
6082	When ``objc_direct_members`` is placed on an ``@implementation`` block,
6083	methods defined in the block are considered to be declared as direct unless
6084	they have been previously declared as non-direct in any interface of the class.
6085	This includes the implicit method definitions introduced by synthesized
6086	properties, including auto-synthesized properties.)reST";
6087
6088	static const char AttrDoc_ObjCException[] = R"reST(No documentation.)reST";
6089
6090	static const char AttrDoc_ObjCExplicitProtocolImpl[] = R"reST(No documentation.)reST";
6091
6092	static const char AttrDoc_ObjCExternallyRetained[] = R"reST(The ``objc_externally_retained`` attribute can be applied to strong local
6093	variables, functions, methods, or blocks to opt into
6094	`externally-retained semantics
6095	<https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables>`_.
6096
6097	When applied to the definition of a function, method, or block, every parameter
6098	of the function with implicit strong retainable object pointer type is
6099	considered externally-retained, and becomes ``const``. By explicitly annotating
6100	a parameter with ``__strong``, you can opt back into the default
6101	non-externally-retained behavior for that parameter. For instance,
6102	``first_param`` is externally-retained below, but not ``second_param``:
6103
6104	.. code-block:: objc
6105
6106	__attribute__((objc_externally_retained))
6107	void f(NSArray first_param, __strong NSArray second_param) {
6108	// ...
6109	}
6110
6111	Likewise, when applied to a strong local variable, that variable becomes
6112	``const`` and is considered externally-retained.
6113
6114	When compiled without ``-fobjc-arc``, this attribute is ignored.)reST";
6115
6116	static const char AttrDoc_ObjCGC[] = R"reST(No documentation.)reST";
6117
6118	static const char AttrDoc_ObjCIndependentClass[] = R"reST(No documentation.)reST";
6119
6120	static const char AttrDoc_ObjCInertUnsafeUnretained[] = R"reST()reST";
6121
6122	static const char AttrDoc_ObjCKindOf[] = R"reST(No documentation.)reST";
6123
6124	static const char AttrDoc_ObjCMethodFamily[] = R"reST(Many methods in Objective-C have conventional meanings determined by their
6125	selectors. It is sometimes useful to be able to mark a method as having a
6126	particular conventional meaning despite not having the right selector, or as
6127	not having the conventional meaning that its selector would suggest. For these
6128	use cases, we provide an attribute to specifically describe the "method family"
6129	that a method belongs to.
6130
6131	Usage: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
6132	``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
6133	attribute can only be placed at the end of a method declaration:
6134
6135	.. code-block:: objc
6136
6137	- (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
6138
6139	Users who do not wish to change the conventional meaning of a method, and who
6140	merely want to document its non-standard retain and release semantics, should
6141	use the retaining behavior attributes (``ns_returns_retained``,
6142	``ns_returns_not_retained``, etc).
6143
6144	Query for this feature with ``__has_attribute(objc_method_family)``.)reST";
6145
6146	static const char AttrDoc_ObjCNSObject[] = R"reST(No documentation.)reST";
6147
6148	static const char AttrDoc_ObjCNonLazyClass[] = R"reST(This attribute can be added to an Objective-C ``@interface`` or
6149	``@implementation`` declaration to add the class to the list of non-lazily
6150	initialized classes. A non-lazy class will be initialized eagerly when the
6151	Objective-C runtime is loaded. This is required for certain system classes which
6152	have instances allocated in non-standard ways, such as the classes for blocks
6153	and constant strings. Adding this attribute is essentially equivalent to
6154	providing a trivial ``+load`` method but avoids the (fairly small) load-time
6155	overheads associated with defining and calling such a method.)reST";
6156
6157	static const char AttrDoc_ObjCNonRuntimeProtocol[] = R"reST(The ``objc_non_runtime_protocol`` attribute can be used to mark that an
6158	Objective-C protocol is only used during static type-checking and doesn't need
6159	to be represented dynamically. This avoids several small code-size and run-time
6160	overheads associated with handling the protocol's metadata. A non-runtime
6161	protocol cannot be used as the operand of a ``@protocol`` expression, and
6162	dynamic attempts to find it with ``objc_getProtocol`` will fail.
6163
6164	If a non-runtime protocol inherits from any ordinary protocols, classes and
6165	derived protocols that declare conformance to the non-runtime protocol will
6166	dynamically list their conformance to those bare protocols.)reST";
6167
6168	static const char AttrDoc_ObjCOwnership[] = R"reST(No documentation.)reST";
6169
6170	static const char AttrDoc_ObjCPreciseLifetime[] = R"reST(No documentation.)reST";
6171
6172	static const char AttrDoc_ObjCRequiresPropertyDefs[] = R"reST(No documentation.)reST";
6173
6174	static const char AttrDoc_ObjCRequiresSuper[] = R"reST(Some Objective-C classes allow a subclass to override a particular method in a
6175	parent class but expect that the overriding method also calls the overridden
6176	method in the parent class. For these cases, we provide an attribute to
6177	designate that a method requires a "call to ``super``" in the overriding
6178	method in the subclass.
6179
6180	Usage: ``__attribute__((objc_requires_super))``. This attribute can only
6181	be placed at the end of a method declaration:
6182
6183	.. code-block:: objc
6184
6185	- (void)foo __attribute__((objc_requires_super));
6186
6187	This attribute can only be applied the method declarations within a class, and
6188	not a protocol. Currently this attribute does not enforce any placement of
6189	where the call occurs in the overriding method (such as in the case of
6190	``-dealloc`` where the call must appear at the end). It checks only that it
6191	exists.
6192
6193	Note that on both OS X and iOS that the Foundation framework provides a
6194	convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
6195	attribute:
6196
6197	.. code-block:: objc
6198
6199	- (void)foo NS_REQUIRES_SUPER;
6200
6201	This macro is conditionally defined depending on the compiler's support for
6202	this attribute. If the compiler does not support the attribute the macro
6203	expands to nothing.
6204
6205	Operationally, when a method has this annotation the compiler will warn if the
6206	implementation of an override in a subclass does not call super. For example:
6207
6208	.. code-block:: objc
6209
6210	warning: method possibly missing a [super AnnotMeth] call
6211	- (void) AnnotMeth{};
6212	^)reST";
6213
6214	static const char AttrDoc_ObjCReturnsInnerPointer[] = R"reST(No documentation.)reST";
6215
6216	static const char AttrDoc_ObjCRootClass[] = R"reST(No documentation.)reST";
6217
6218	static const char AttrDoc_ObjCRuntimeName[] = R"reST(By default, the Objective-C interface or protocol identifier is used
6219	in the metadata name for that object. The ``objc_runtime_name``
6220	attribute allows annotated interfaces or protocols to use the
6221	specified string argument in the object's metadata name instead of the
6222	default name.
6223
6224	Usage: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute
6225	can only be placed before an @protocol or @interface declaration:
6226
6227	.. code-block:: objc
6228
6229	__attribute__((objc_runtime_name("MyLocalName")))
6230	@interface Message
6231	@end)reST";
6232
6233	static const char AttrDoc_ObjCRuntimeVisible[] = R"reST(This attribute specifies that the Objective-C class to which it applies is
6234	visible to the Objective-C runtime but not to the linker. Classes annotated
6235	with this attribute cannot be subclassed and cannot have categories defined for
6236	them.)reST";
6237
6238	static const char AttrDoc_ObjCSubclassingRestricted[] = R"reST(This attribute can be added to an Objective-C ``@interface`` declaration to
6239	ensure that this class cannot be subclassed.)reST";
6240
6241	static const char AttrDoc_OpenACCRoutineAnnot[] = R"reST()reST";
6242
6243	static const char AttrDoc_OpenACCRoutineDecl[] = R"reST()reST";
6244
6245	static const char AttrDoc_OpenCLAccess[] = R"reST(The access qualifiers must be used with image object arguments or pipe arguments
6246	to declare if they are being read or written by a kernel or function.
6247
6248	The read_only/__read_only, write_only/__write_only and read_write/__read_write
6249	names are reserved for use as access qualifiers and shall not be used otherwise.
6250
6251	.. code-block:: c
6252
6253	kernel void
6254	foo (read_only image2d_t imageA,
6255	write_only image2d_t imageB) {
6256	...
6257	}
6258
6259	In the above example imageA is a read-only 2D image object, and imageB is a
6260	write-only 2D image object.
6261
6262	The read_write (or __read_write) qualifier can not be used with pipe.
6263
6264	More details can be found in the OpenCL C language Spec v2.0, Section 6.6.)reST";
6265
6266	static const char AttrDoc_OpenCLConstantAddressSpace[] = R"reST(The constant address space attribute signals that an object is located in
6267	a constant (non-modifiable) memory region. It is available to all work items.
6268	Any type can be annotated with the constant address space attribute. Objects
6269	with the constant address space qualifier can be declared in any scope and must
6270	have an initializer.)reST";
6271
6272	static const char AttrDoc_OpenCLGenericAddressSpace[] = R"reST(The generic address space attribute is only available with OpenCL v2.0 and later.
6273	It can be used with pointer types. Variables in global and local scope and
6274	function parameters in non-kernel functions can have the generic address space
6275	type attribute. It is intended to be a placeholder for any other address space
6276	except for '__constant' in OpenCL code which can be used with multiple address
6277	spaces.)reST";
6278
6279	static const char AttrDoc_OpenCLGlobalAddressSpace[] = R"reST(The global address space attribute specifies that an object is allocated in
6280	global memory, which is accessible by all work items. The content stored in this
6281	memory area persists between kernel executions. Pointer types to the global
6282	address space are allowed as function parameters or local variables. Starting
6283	with OpenCL v2.0, the global address space can be used with global (program
6284	scope) variables and static local variable as well.)reST";
6285
6286	static const char AttrDoc_OpenCLGlobalDeviceAddressSpace[] = R"reST(The ``global_device`` and ``global_host`` address space attributes specify that
6287	an object is allocated in global memory on the device/host. It helps to
6288	distinguish USM (Unified Shared Memory) pointers that access global device
6289	memory from those that access global host memory. These new address spaces are
6290	a subset of the ``__global/opencl_global`` address space, the full address space
6291	set model for OpenCL 2.0 with the extension looks as follows:
6292
6293	\| generic->global->host
6294	\| ->device
6295	\| ->private
6296	\| ->local
6297	\| constant
6298
6299	As ``global_device`` and ``global_host`` are a subset of
6300	``__global/opencl_global`` address spaces it is allowed to convert
6301	``global_device`` and ``global_host`` address spaces to
6302	``__global/opencl_global`` address spaces (following ISO/IEC TR 18037 5.1.3
6303	"Address space nesting and rules for pointers").)reST";
6304
6305	static const char AttrDoc_OpenCLGlobalHostAddressSpace[] = R"reST(The ``global_device`` and ``global_host`` address space attributes specify that
6306	an object is allocated in global memory on the device/host. It helps to
6307	distinguish USM (Unified Shared Memory) pointers that access global device
6308	memory from those that access global host memory. These new address spaces are
6309	a subset of the ``__global/opencl_global`` address space, the full address space
6310	set model for OpenCL 2.0 with the extension looks as follows:
6311
6312	\| generic->global->host
6313	\| ->device
6314	\| ->private
6315	\| ->local
6316	\| constant
6317
6318	As ``global_device`` and ``global_host`` are a subset of
6319	``__global/opencl_global`` address spaces it is allowed to convert
6320	``global_device`` and ``global_host`` address spaces to
6321	``__global/opencl_global`` address spaces (following ISO/IEC TR 18037 5.1.3
6322	"Address space nesting and rules for pointers").)reST";
6323
6324	static const char AttrDoc_OpenCLIntelReqdSubGroupSize[] = R"reST(The optional attribute intel_reqd_sub_group_size can be used to indicate that
6325	the kernel must be compiled and executed with the specified subgroup size. When
6326	this attribute is present, get_max_sub_group_size() is guaranteed to return the
6327	specified integer value. This is important for the correctness of many subgroup
6328	algorithms, and in some cases may be used by the compiler to generate more optimal
6329	code. See `cl_intel_required_subgroup_size
6330	<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
6331	for details.)reST";
6332
6333	static const char AttrDoc_OpenCLLocalAddressSpace[] = R"reST(The local address space specifies that an object is allocated in the local (work
6334	group) memory area, which is accessible to all work items in the same work
6335	group. The content stored in this memory region is not accessible after
6336	the kernel execution ends. In a kernel function scope, any variable can be in
6337	the local address space. In other scopes, only pointer types to the local address
6338	space are allowed. Local address space variables cannot have an initializer.)reST";
6339
6340	static const char AttrDoc_OpenCLPrivateAddressSpace[] = R"reST(The private address space specifies that an object is allocated in the private
6341	(work item) memory. Other work items cannot access the same memory area and its
6342	content is destroyed after work item execution ends. Local variables can be
6343	declared in the private address space. Function arguments are always in the
6344	private address space. Kernel function arguments of a pointer or an array type
6345	cannot point to the private address space.)reST";
6346
6347	static const char AttrDoc_OpenCLUnrollHint[] = R"reST(The opencl_unroll_hint attribute qualifier can be used to specify that a loop
6348	(for, while and do loops) can be unrolled. This attribute qualifier can be
6349	used to specify full unrolling or partial unrolling by a specified amount.
6350	This is a compiler hint and the compiler may ignore this directive. See
6351	`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
6352	s6.11.5 for details.)reST";
6353
6354	static const char AttrDoc_OptimizeNone[] = R"reST(The ``optnone`` attribute suppresses essentially all optimizations
6355	on a function or method, regardless of the optimization level applied to
6356	the compilation unit as a whole. This is particularly useful when you
6357	need to debug a particular function, but it is infeasible to build the
6358	entire application without optimization. Avoiding optimization on the
6359	specified function can improve the quality of the debugging information
6360	for that function.
6361
6362	This attribute is incompatible with the ``always_inline`` and ``minsize``
6363	attributes.
6364
6365	Note that this attribute does not apply recursively to nested functions such as
6366	lambdas or blocks when using declaration-specific attribute syntaxes such as double
6367	square brackets (``[[]]``) or ``__attribute__``. The ``#pragma`` syntax can be
6368	used to apply the attribute to all functions, including nested functions, in a
6369	range of source code.)reST";
6370
6371	static const char AttrDoc_Overloadable[] = R"reST(Clang provides support for C++ function overloading in C. Function overloading
6372	in C is introduced using the ``overloadable`` attribute. For example, one
6373	might provide several overloaded versions of a ``tgsin`` function that invokes
6374	the appropriate standard function computing the sine of a value with ``float``,
6375	``double``, or ``long double`` precision:
6376
6377	.. code-block:: c
6378
6379	#include <math.h>
6380	float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
6381	double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
6382	long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
6383
6384	Given these declarations, one can call ``tgsin`` with a ``float`` value to
6385	receive a ``float`` result, with a ``double`` to receive a ``double`` result,
6386	etc. Function overloading in C follows the rules of C++ function overloading
6387	to pick the best overload given the call arguments, with a few C-specific
6388	semantics:
6389
6390	* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
6391	floating-point promotion (per C99) rather than as a floating-point conversion
6392	(as in C++).
6393
6394	* A conversion from a pointer of type ``T`` to a pointer of type ``U`` is
6395	considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
6396	compatible types.
6397
6398	* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
6399	and ``U`` are compatible types. This conversion is given "conversion" rank.
6400
6401	* If no viable candidates are otherwise available, we allow a conversion from a
6402	pointer of type ``T`` to a pointer of type ``U``, where ``T`` and ``U`` are
6403	incompatible. This conversion is ranked below all other types of conversions.
6404	Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
6405	for ``T`` and ``U`` to be incompatible.
6406
6407	The declaration of ``overloadable`` functions is restricted to function
6408	declarations and definitions. If a function is marked with the ``overloadable``
6409	attribute, then all declarations and definitions of functions with that name,
6410	except for at most one (see the note below about unmarked overloads), must have
6411	the ``overloadable`` attribute. In addition, redeclarations of a function with
6412	the ``overloadable`` attribute must have the ``overloadable`` attribute, and
6413	redeclarations of a function without the ``overloadable`` attribute must not
6414	have the ``overloadable`` attribute. e.g.,
6415
6416	.. code-block:: c
6417
6418	int f(int) __attribute__((overloadable));
6419	float f(float); // error: declaration of "f" must have the "overloadable" attribute
6420	int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
6421
6422	int g(int) __attribute__((overloadable));
6423	int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
6424
6425	int h(int);
6426	int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
6427	// have the "overloadable" attribute
6428
6429	Functions marked ``overloadable`` must have prototypes. Therefore, the
6430	following code is ill-formed:
6431
6432	.. code-block:: c
6433
6434	int h() __attribute__((overloadable)); // error: h does not have a prototype
6435
6436	However, ``overloadable`` functions are allowed to use a ellipsis even if there
6437	are no named parameters (as is permitted in C++). This feature is particularly
6438	useful when combined with the ``unavailable`` attribute:
6439
6440	.. code-block:: c++
6441
6442	void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
6443
6444	Functions declared with the ``overloadable`` attribute have their names mangled
6445	according to the same rules as C++ function names. For example, the three
6446	``tgsin`` functions in our motivating example get the mangled names
6447	``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
6448	caveats to this use of name mangling:
6449
6450	* Future versions of Clang may change the name mangling of functions overloaded
6451	in C, so you should not depend on an specific mangling. To be completely
6452	safe, we strongly urge the use of ``static inline`` with ``overloadable``
6453	functions.
6454
6455	* The ``overloadable`` attribute has almost no meaning when used in C++,
6456	because names will already be mangled and functions are already overloadable.
6457	However, when an ``overloadable`` function occurs within an ``extern "C"``
6458	linkage specification, its name will be mangled in the same way as it
6459	would in C.
6460
6461	For the purpose of backwards compatibility, at most one function with the same
6462	name as other ``overloadable`` functions may omit the ``overloadable``
6463	attribute. In this case, the function without the ``overloadable`` attribute
6464	will not have its name mangled.
6465
6466	For example:
6467
6468	.. code-block:: c
6469
6470	// Notes with mangled names assume Itanium mangling.
6471	int f(int);
6472	int f(double) __attribute__((overloadable));
6473	void foo() {
6474	f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
6475	// was marked with overloadable).
6476	f(1.0); // Emits a call to _Z1fd.
6477	}
6478
6479	Support for unmarked overloads is not present in some versions of clang. You may
6480	query for it using ``__has_extension(overloadable_unmarked)``.
6481
6482	Query for this attribute with ``__has_attribute(overloadable)``.)reST";
6483
6484	static const char AttrDoc_Override[] = R"reST()reST";
6485
6486	static const char AttrDoc_Owner[] = R"reST(.. Note:: This attribute is experimental and its effect on analysis is subject to change in
6487	a future version of clang.
6488
6489	The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an
6490	object of type ``T``:
6491
6492	.. code::
6493
6494	class [[gsl::Owner(int)]] IntOwner {
6495	private:
6496	int value;
6497	public:
6498	int *getInt() { return &value; }
6499	};
6500
6501	The argument ``T`` is optional and is ignored.
6502	This attribute may be used by analysis tools and has no effect on code
6503	generation. A ``void`` argument means that the class can own any type.
6504
6505	See Pointer_ for an example.)reST";
6506
6507	static const char AttrDoc_Ownership[] = R"reST(.. note::
6508
6509	In order for the Clang Static Analyzer to acknowledge these attributes, the
6510	``Optimistic`` config needs to be set to true for the checker
6511	``unix.DynamicMemoryModeling``:
6512
6513	``-Xclang -analyzer-config -Xclang unix.DynamicMemoryModeling:Optimistic=true``
6514
6515	These attributes are used by the Clang Static Analyzer's dynamic memory modeling
6516	facilities to mark custom allocating/deallocating functions.
6517
6518	All 3 attributes' first parameter of type string is the type of the allocation:
6519	``malloc``, ``new``, etc. to allow for catching :ref:`mismatched deallocation
6520	<unix-MismatchedDeallocator>` bugs. The allocation type can be any string, e.g.
6521	a function annotated with
6522	returning a piece of memory of type ``lasagna`` but freed with a function
6523	annotated to release ``cheese`` typed memory will result in mismatched
6524	deallocation warning.
6525
6526	The (currently) only allocation type having special meaning is ``malloc`` --
6527	the Clang Static Analyzer makes sure that allocating functions annotated with
6528	``malloc`` are treated like they used the standard ``malloc()``, and can be
6529	safely deallocated with the standard ``free()``.
6530
6531	* Use ``ownership_returns`` to mark a function as an allocating function. Takes
6532	1 parameter to denote the allocation type.
6533	* Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2
6534	parameters: the allocation type, and the index of the parameter that is being
6535	deallocated (counting from 1).
6536	* Use ``ownership_holds`` to mark that a function takes over the ownership of a
6537	piece of memory and will free it at some unspecified point in the future. Like
6538	``ownership_takes``, this takes 2 parameters: the allocation type, and the
6539	index of the parameter whose ownership will be taken over (counting from 1).
6540
6541	The annotations ``ownership_takes`` and ``ownership_holds`` both prevent memory
6542	leak reports (concerning the specified argument); the difference between them
6543	is that using taken memory is a use-after-free error, while using held memory
6544	is assumed to be legitimate.
6545
6546	Example:
6547
6548	.. code-block:: c
6549
6550	// Denotes that my_malloc will return with a dynamically allocated piece of
6551	// memory using malloc().
6552	void __attribute((ownership_returns(malloc))) *my_malloc(size_t);
6553
6554	// Denotes that my_free will deallocate its parameter using free().
6555	void __attribute((ownership_takes(malloc, 1))) my_free(void *);
6556
6557	// Denotes that my_hold will take over the ownership of its parameter that was
6558	// allocated via malloc().
6559	void __attribute((ownership_holds(malloc, 1))) my_hold(void *);
6560
6561	Further reading about dynamic memory modeling in the Clang Static Analyzer is
6562	found in these checker docs:
6563	:ref:`unix.Malloc <unix-Malloc>`, :ref:`unix.MallocSizeof <unix-MallocSizeof>`,
6564	:ref:`unix.MismatchedDeallocator <unix-MismatchedDeallocator>`,
6565	:ref:`cplusplus.NewDelete <cplusplus-NewDelete>`,
6566	:ref:`cplusplus.NewDeleteLeaks <cplusplus-NewDeleteLeaks>`,
6567	:ref:`optin.taint.TaintedAlloc <optin-taint-TaintedAlloc>`.
6568	Mind that many more checkers are affected by dynamic memory modeling changes to
6569	some extent.
6570
6571	Further reading for other annotations:
6572	`Source Annotations in the Clang Static Analyzer <https://clang.llvm.org/docs/analyzer/user-docs/Annotations.html>`_.)reST";
6573
6574	static const char AttrDoc_Packed[] = R"reST(No documentation.)reST";
6575
6576	static const char AttrDoc_ParamTypestate[] = R"reST(This attribute specifies expectations about function parameters. Calls to an
6577	function with annotated parameters will issue a warning if the corresponding
6578	argument isn't in the expected state. The attribute is also used to set the
6579	initial state of the parameter when analyzing the function's body.)reST";
6580
6581	static const char AttrDoc_Pascal[] = R"reST(No documentation.)reST";
6582
6583	static const char AttrDoc_PassObjectSize[] = R"reST(.. Note:: The mangling of functions with parameters that are annotated with
6584	``pass_object_size`` is subject to change. You can get around this by
6585	using ``__asm__("foo")`` to explicitly name your functions, thus preserving
6586	your ABI; also, non-overloadable C functions with ``pass_object_size`` are
6587	not mangled.
6588
6589	The ``pass_object_size(Type)`` attribute can be placed on function parameters to
6590	instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
6591	of said function, and implicitly pass the result of this call in as an invisible
6592	argument of type ``size_t`` directly after the parameter annotated with
6593	``pass_object_size``. Clang will also replace any calls to
6594	``__builtin_object_size(param, Type)`` in the function by said implicit
6595	parameter.
6596
6597	Example usage:
6598
6599	.. code-block:: c
6600
6601	int bzero1(char *const p __attribute__((pass_object_size(0))))
6602	__attribute__((noinline)) {
6603	int i = 0;
6604	for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
6605	p[i] = 0;
6606	}
6607	return i;
6608	}
6609
6610	int main() {
6611	char chars[100];
6612	int n = bzero1(&chars[0]);
6613	assert(n == sizeof(chars));
6614	return 0;
6615	}
6616
6617	If successfully evaluating ``__builtin_object_size(param, Type)`` at the
6618	callsite is not possible, then the "failed" value is passed in. So, using the
6619	definition of ``bzero1`` from above, the following code would exit cleanly:
6620
6621	.. code-block:: c
6622
6623	int main2(int argc, char *argv[]) {
6624	int n = bzero1(argv);
6625	assert(n == -1);
6626	return 0;
6627	}
6628
6629	``pass_object_size`` plays a part in overload resolution. If two overload
6630	candidates are otherwise equally good, then the overload with one or more
6631	parameters with ``pass_object_size`` is preferred. This implies that the choice
6632	between two identical overloads both with ``pass_object_size`` on one or more
6633	parameters will always be ambiguous; for this reason, having two such overloads
6634	is illegal. For example:
6635
6636	.. code-block:: c++
6637
6638	#define PS(N) __attribute__((pass_object_size(N)))
6639	// OK
6640	void Foo(char a, char b); // Overload A
6641	// OK -- overload A has no parameters with pass_object_size.
6642	void Foo(char a PS(0), char b PS(0)); // Overload B
6643	// Error -- Same signature (sans pass_object_size) as overload B, and both
6644	// overloads have one or more parameters with the pass_object_size attribute.
6645	void Foo(void a PS(0), void b);
6646
6647	// OK
6648	void Bar(void *a PS(0)); // Overload C
6649	// OK
6650	void Bar(char *c PS(1)); // Overload D
6651
6652	void main() {
6653	char known[10], *unknown;
6654	Foo(unknown, unknown); // Calls overload B
6655	Foo(known, unknown); // Calls overload B
6656	Foo(unknown, known); // Calls overload B
6657	Foo(known, known); // Calls overload B
6658
6659	Bar(known); // Calls overload D
6660	Bar(unknown); // Calls overload D
6661	}
6662
6663	Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
6664
6665	* Only one use of ``pass_object_size`` is allowed per parameter.
6666
6667	* It is an error to take the address of a function with ``pass_object_size`` on
6668	any of its parameters. If you wish to do this, you can create an overload
6669	without ``pass_object_size`` on any parameters.
6670
6671	* It is an error to apply the ``pass_object_size`` attribute to parameters that
6672	are not pointers. Additionally, any parameter that ``pass_object_size`` is
6673	applied to must be marked ``const`` at its function's definition.
6674
6675	Clang also supports the ``pass_dynamic_object_size`` attribute, which behaves
6676	identically to ``pass_object_size``, but evaluates a call to
6677	``__builtin_dynamic_object_size`` at the callee instead of
6678	``__builtin_object_size``. ``__builtin_dynamic_object_size`` provides some extra
6679	runtime checks when the object size can't be determined at compile-time. You can
6680	read more about ``__builtin_dynamic_object_size`` `here
6681	<https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically>`_.)reST";
6682
6683	static const char AttrDoc_PatchableFunctionEntry[] = R"reST(``__attribute__((patchable_function_entry(N,M,Section)))`` is used to generate M
6684	NOPs before the function entry and N-M NOPs after the function entry, with a record of
6685	the entry stored in section ``Section``. This attribute takes precedence over the
6686	command line option ``-fpatchable-function-entry=N,M,Section``. ``M`` defaults to 0
6687	if omitted.``Section`` defaults to the ``-fpatchable-function-entry`` section name if
6688	set, or to ``__patchable_function_entries`` otherwise.
6689
6690	This attribute is only supported on
6691	aarch64/aarch64-be/loongarch32/loongarch64/riscv32/riscv64/i386/x86-64/ppc/ppc64/ppc64le/s390x targets.
6692	For ppc/ppc64 targets, AIX is still not supported.)reST";
6693
6694	static const char AttrDoc_Pcs[] = R"reST(On ARM targets, this attribute can be used to select calling conventions
6695	similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
6696	"aapcs-vfp".)reST";
6697
6698	static const char AttrDoc_Pointer[] = R"reST(.. Note:: This attribute is experimental and its effect on analysis is subject to change in
6699	a future version of clang.
6700
6701	The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave
6702	like pointers to an object of type ``T``:
6703
6704	.. code::
6705
6706	class [[gsl::Pointer(int)]] IntPointer {
6707	private:
6708	int *valuePointer;
6709	public:
6710	IntPointer(const IntOwner&);
6711	int *getInt() { return valuePointer; }
6712	};
6713
6714	The argument ``T`` is optional and is ignored.
6715	This attribute may be used by analysis tools and has no effect on code
6716	generation. A ``void`` argument means that the pointer can point to any type.
6717
6718	Example:
6719	When constructing an instance of a class annotated like this (a Pointer) from
6720	an instance of a class annotated with ``[[gsl::Owner]]`` (an Owner),
6721	then the analysis will consider the Pointer to point inside the Owner.
6722	When the Owner's lifetime ends, it will consider the Pointer to be dangling.
6723
6724	.. code-block:: c++
6725
6726	int f() {
6727	IntPointer P(IntOwner{}); // P "points into" a temporary IntOwner object
6728	P.getInt(); // P is dangling
6729	}
6730
6731	Transparent Member Functions
6732
6733	The analysis automatically tracks certain member functions of ``[[gsl::Pointer]]`` types
6734	that provide transparent access to the pointed-to object. These include:
6735
6736	* Dereference operators: ``operator*``, ``operator->``
6737	* Data access methods: ``data()``, ``c_str()``, ``get()``
6738	* Iterator methods: ``begin()``, ``end()``, ``rbegin()``, ``rend()``, ``cbegin()``, ``cend()``, ``crbegin()``, ``crend()``
6739
6740	When these methods return pointers, view types, or references, the analysis treats them as
6741	transparently borrowing from the same object that the pointer itself borrows from,
6742	enabling detection of use-after-free through these access patterns:
6743
6744	.. code-block:: c++
6745
6746	// For example, .data() here returns a borrow to 's' instead of 'v'.
6747	const char* f() {
6748	std::string s = "hello";
6749	std::string_view v = s; // warning: address of stack memory returned
6750	return v.data(); // note: returned here
6751	}
6752
6753	const MyObj& g(MyObj obj) {
6754	View v = obj; // warning: address of stack memory returned
6755	return *v; // note: returned here
6756	}
6757
6758	This tracking also applies to range-based for loops, where the ``begin()`` and ``end()``
6759	iterators are used to access elements:
6760
6761	.. code-block:: c++
6762
6763	std::string_view f(std::vector<std::string> vec) {
6764	for (const std::string& s : vec) { // warning: address of stack memory returned
6765	return s; // note: returned here
6766	}
6767	}
6768
6769	Container Template Specialization
6770
6771	If a template class is annotated with ``[[gsl::Owner]]``, and the first
6772	instantiated template argument is a pointer type (raw pointer, or ``[[gsl::Pointer]]``),
6773	the analysis will consider the instantiated class as a container of the pointer.
6774	When constructing such an object from a GSL owner object, the analysis will
6775	assume that the container holds a pointer to the owner object. Consequently,
6776	when the owner object is destroyed, the pointer will be considered dangling.
6777
6778	.. code-block:: c++
6779
6780	int f() {
6781	std::vector<std::string_view> v = {std::string()}; // v holds a dangling pointer.
6782	std::optional<std::string_view> o = std::string(); // o holds a dangling pointer.
6783	})reST";
6784
6785	static const char AttrDoc_PointerAuth[] = R"reST(The ``__ptrauth`` qualifier allows the programmer to directly control
6786	how pointers are signed when they are stored in a particular variable.
6787	This can be used to strengthen the default protections of pointer
6788	authentication and make it more difficult for an attacker to escalate
6789	an ability to alter memory into full control of a process.
6790
6791	.. code-block:: c
6792
6793	#include <ptrauth.h>
6794
6795	typedef void (my_callback)(const void);
6796	my_callback __ptrauth(ptrauth_key_process_dependent_code, 1, 0xe27a) callback;
6797
6798	The first argument to ``__ptrauth`` is the name of the signing key.
6799	Valid key names for the target are defined in ``<ptrauth.h>``.
6800
6801	The second argument to ``__ptrauth`` is a flag (0 or 1) specifying whether
6802	the object should use address discrimination.
6803
6804	The third argument to ``__ptrauth`` is a 16-bit non-negative integer which
6805	allows additional discrimination between objects.)reST";
6806
6807	static const char AttrDoc_PragmaClangBSSSection[] = R"reST()reST";
6808
6809	static const char AttrDoc_PragmaClangDataSection[] = R"reST()reST";
6810
6811	static const char AttrDoc_PragmaClangRelroSection[] = R"reST()reST";
6812
6813	static const char AttrDoc_PragmaClangRodataSection[] = R"reST()reST";
6814
6815	static const char AttrDoc_PragmaClangTextSection[] = R"reST()reST";
6816
6817	static const char AttrDoc_PreferredName[] = R"reST(The ``preferred_name`` attribute can be applied to a class template, and
6818	specifies a preferred way of naming a specialization of the template. The
6819	preferred name will be used whenever the corresponding template specialization
6820	would otherwise be printed in a diagnostic or similar context.
6821
6822	The preferred name must be a typedef or type alias declaration that refers to a
6823	specialization of the class template (not including any type qualifiers). In
6824	general this requires the template to be declared at least twice. For example:
6825
6826	.. code-block:: c++
6827
6828	template<typename T> struct basic_string;
6829	using string = basic_string<char>;
6830	using wstring = basic_string<wchar_t>;
6831	template<typename T> struct [[clang::preferred_name(string),
6832	clang::preferred_name(wstring)]] basic_string {
6833	// ...
6834	};
6835
6836
6837	Note that the ``preferred_name`` attribute will be ignored when the compiler
6838	writes a C++20 Module interface now. This is due to a compiler issue
6839	(https://github.com/llvm/llvm-project/issues/56490) that blocks users to modularize
6840	declarations with `preferred_name`. This is intended to be fixed in the future.)reST";
6841
6842	static const char AttrDoc_PreferredType[] = R"reST(This attribute allows adjusting the type of a bit-field in debug information.
6843	This can be helpful when a bit-field is intended to store an enumeration value,
6844	but has to be specified as having the enumeration's underlying type in order to
6845	facilitate compiler optimizations or bit-field packing behavior. Normally, the
6846	underlying type is what is emitted in debug information, which can make it hard
6847	for debuggers to know to map a bit-field's value back to a particular enumeration.
6848
6849	.. code-block:: c++
6850
6851	enum Colors { Red, Green, Blue };
6852
6853	struct S {
6854	[[clang::preferred_type(Colors)]] unsigned ColorVal : 2;
6855	[[clang::preferred_type(bool)]] unsigned UseAlternateColorSpace : 1;
6856	} s = { Green, false };
6857
6858	Without the attribute, a debugger is likely to display the value ``1`` for ``ColorVal``
6859	and ``0`` for ``UseAlternateColorSpace``. With the attribute, the debugger may now
6860	display ``Green`` and ``false`` instead.
6861
6862	This can be used to map a bit-field to an arbitrary type that isn't integral
6863	or an enumeration type. For example:
6864
6865	.. code-block:: c++
6866
6867	struct A {
6868	short a1;
6869	short a2;
6870	};
6871
6872	struct B {
6873	[[clang::preferred_type(A)]] unsigned b1 : 32 = 0x000F'000C;
6874	};
6875
6876	will associate the type ``A`` with the ``b1`` bit-field and is intended to display
6877	something like this in the debugger:
6878
6879	.. code-block:: text
6880
6881	Process 2755547 stopped
6882	* thread #1, name = 'test-preferred-', stop reason = step in
6883	frame #0: 0x0000555555555148 test-preferred-type`main at test.cxx:13:14
6884	10 int main()
6885	11 {
6886	12 B b;
6887	-> 13 return b.b1;
6888	14 }
6889	(lldb) v -T
6890	(B) b = {
6891	(A:32) b1 = {
6892	(short) a1 = 12
6893	(short) a2 = 15
6894	}
6895	}
6896
6897	Note that debuggers may not be able to handle more complex mappings, and so
6898	this usage is debugger-dependent.)reST";
6899
6900	static const char AttrDoc_PreserveAll[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of
6901	a function. The ``preserve_all`` calling convention attempts to make the code
6902	in the caller even less intrusive than the ``preserve_most`` calling convention.
6903	This calling convention also behaves identical to the ``C`` calling convention
6904	on how arguments and return values are passed, but it uses a different set of
6905	caller/callee-saved registers. This removes the burden of saving and
6906	recovering a large register set before and after the call in the caller. If
6907	the arguments are passed in callee-saved registers, then they will be
6908	preserved by the callee across the call. This doesn't apply for values
6909	returned in callee-saved registers.
6910
6911	- On X86-64 the callee preserves all general purpose registers, except for
6912	R11. R11 can be used as a scratch register. Furthermore it also preserves
6913	all floating-point registers (XMMs/YMMs).
6914
6915	- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
6916	X16-X18. Furthermore it also preserves lower 128 bits of V8-V31 SIMD - floating
6917	point registers.
6918
6919	The idea behind this convention is to support calls to runtime functions
6920	that don't need to call out to any other functions.
6921
6922	This calling convention, like the ``preserve_most`` calling convention, will be
6923	used by a future version of the Objective-C runtime and should be considered
6924	experimental at this time.)reST";
6925
6926	static const char AttrDoc_PreserveMost[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of
6927	a function. The ``preserve_most`` calling convention attempts to make the code
6928	in the caller as unintrusive as possible. This convention behaves identically
6929	to the ``C`` calling convention on how arguments and return values are passed,
6930	but it uses a different set of caller/callee-saved registers. This alleviates
6931	the burden of saving and recovering a large register set before and after the
6932	call in the caller. If the arguments are passed in callee-saved registers,
6933	then they will be preserved by the callee across the call. This doesn't
6934	apply for values returned in callee-saved registers.
6935
6936	- On X86-64 the callee preserves all general purpose registers, except for
6937	R11. R11 can be used as a scratch register. Floating-point registers
6938	(XMMs/YMMs) are not preserved and need to be saved by the caller.
6939
6940	- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
6941	X16-X18.
6942
6943	The idea behind this convention is to support calls to runtime functions
6944	that have a hot path and a cold path. The hot path is usually a small piece
6945	of code that doesn't use many registers. The cold path might need to call out to
6946	another function and therefore only needs to preserve the caller-saved
6947	registers, which haven't already been saved by the caller. The
6948	``preserve_most`` calling convention is very similar to the ``cold`` calling
6949	convention in terms of caller/callee-saved registers, but they are used for
6950	different types of function calls. ``coldcc`` is for function calls that are
6951	rarely executed, whereas ``preserve_most`` function calls are intended to be
6952	on the hot path and definitely executed a lot. Furthermore ``preserve_most``
6953	doesn't prevent the inliner from inlining the function call.
6954
6955	This calling convention will be used by a future version of the Objective-C
6956	runtime and should therefore still be considered experimental at this time.
6957	Although this convention was created to optimize certain runtime calls to
6958	the Objective-C runtime, it is not limited to this runtime and might be used
6959	by other runtimes in the future too. The current implementation only
6960	supports X86-64 and AArch64, but the intention is to support more architectures
6961	in the future.)reST";
6962
6963	static const char AttrDoc_PreserveNone[] = R"reST(On X86-64 and AArch64 targets, this attribute changes the calling convention of a function.
6964	The ``preserve_none`` calling convention tries to preserve as few general
6965	registers as possible. So all general registers are caller saved registers. It
6966	also uses more general registers to pass arguments. This attribute doesn't
6967	impact floating-point registers. ``preserve_none``'s ABI is still unstable, and
6968	may be changed in the future.
6969
6970	- On X86-64, only RSP and RBP are preserved by the callee.
6971	Registers R12, R13, R14, R15, RDI, RSI, RDX, RCX, R8, R9, R11, and RAX now can
6972	be used to pass function arguments. Floating-point registers (XMMs/YMMs) still
6973	follow the C calling convention.
6974	- On AArch64, only LR and FP are preserved by the callee.
6975	Registers X20-X28, X0-X7, and X9-X14 are used to pass function arguments.
6976	X8, X16-X19, SIMD and floating-point registers follow the AAPCS calling
6977	convention. X15 is not available for argument passing on Windows, but is
6978	used to pass arguments on other platforms.)reST";
6979
6980	static const char AttrDoc_PtGuardedBy[] = R"reST(No documentation.)reST";
6981
6982	static const char AttrDoc_PtGuardedVar[] = R"reST(No documentation.)reST";
6983
6984	static const char AttrDoc_Ptr32[] = R"reST(The ``__ptr32`` qualifier represents a native pointer on a 32-bit system. On a
6985	64-bit system, a pointer with ``__ptr32`` is extended to a 64-bit pointer. The
6986	``__sptr`` and ``__uptr`` qualifiers can be used to specify whether the pointer
6987	is sign extended or zero extended. This qualifier is enabled under
6988	``-fms-extensions``.)reST";
6989
6990	static const char AttrDoc_Ptr64[] = R"reST(The ``__ptr64`` qualifier represents a native pointer on a 64-bit system. On a
6991	32-bit system, a ``__ptr64`` pointer is truncated to a 32-bit pointer. This
6992	qualifier is enabled under ``-fms-extensions``.)reST";
6993
6994	static const char AttrDoc_Pure[] = R"reST(No documentation.)reST";
6995
6996	static const char AttrDoc_RISCVInterrupt[] = R"reST(Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV
6997	targets. This attribute may be attached to a function definition and instructs
6998	the backend to generate appropriate function entry/exit code so that it can be
6999	used directly as an interrupt service routine.
7000
7001	Permissible values for this parameter are ``machine``, ``supervisor``,
7002	``rnmi``, ``qci-nest``, ``qci-nonest``, ``SiFive-CLIC-preemptible``, and
7003	``SiFive-CLIC-stack-swap``. If there is no parameter, then it defaults to
7004	``machine``.
7005
7006	The ``rnmi`` value is used for resumable non-maskable interrupts. It requires the
7007	standard Smrnmi extension.
7008
7009	The ``qci-nest`` and ``qci-nonest`` values require Qualcomm's Xqciint extension
7010	and are used for Machine-mode Interrupts and Machine-mode Non-maskable
7011	interrupts. These use the following instructions from Xqciint to save and
7012	restore interrupt state to the stack -- the ``qci-nest`` value will use
7013	``qc.c.mienter.nest`` and the ``qci-nonest`` value will use ``qc.c.mienter`` to
7014	begin the interrupt handler. Both of these will use ``qc.c.mileaveret`` to
7015	restore the state and return to the previous context.
7016
7017	The ``SiFive-CLIC-preemptible`` and ``SiFive-CLIC-stack-swap`` values are used
7018	for machine-mode interrupts. For ``SiFive-CLIC-preemptible`` interrupts, the
7019	values of ``mcause`` and ``mepc`` are saved onto the stack, and interrupts are
7020	re-enabled. For ``SiFive-CLIC-stack-swap`` interrupts, the stack pointer is
7021	swapped with ``mscratch`` before its first use and after its last use.
7022
7023	The SiFive CLIC values may be combined with each other and with the ``machine``
7024	attribute value. Any other combination of different values is not allowed.
7025
7026	Repeated interrupt attribute on the same declaration will cause a warning
7027	to be emitted. In case of repeated declarations, the last one prevails.
7028
7029	Refer to:
7030	https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
7031	https://riscv.org/specifications/privileged-isa/
7032	The RISC-V Instruction Set Manual Volume II: Privileged Architecture
7033	Version 1.10.
7034	https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0
7035	https://sifive.cdn.prismic.io/sifive/d1984d2b-c9b9-4c91-8de0-d68a5e64fa0f_sifive-interrupt-cookbook-v1p2.pdf)reST";
7036
7037	static const char AttrDoc_RISCVVLSCC[] = R"reST(The ``riscv_vls_cc`` attribute can be applied to a function. Functions
7038	declared with this attribute will utilize the standard fixed-length vector
7039	calling convention variant instead of the default calling convention defined by
7040	the ABI. This variant aims to pass fixed-length vectors via vector registers,
7041	if possible, rather than through general-purpose registers.)reST";
7042
7043	static const char AttrDoc_RISCVVectorCC[] = R"reST(The ``riscv_vector_cc`` attribute can be applied to a function. It preserves 15
7044	registers namely, v1-v7 and v24-v31 as callee-saved. Callers thus don't need
7045	to save these registers before function calls, and callees only need to save
7046	them if they use them.)reST";
7047
7048	static const char AttrDoc_RandomizeLayout[] = R"reST(The attribute ``randomize_layout``, when attached to a C structure, selects it
7049	for structure layout field randomization; a compile-time hardening technique. A
7050	"seed" value, is specified via the ``-frandomize-layout-seed=`` command line flag.
7051	For example:
7052
7053	.. code-block:: bash
7054
7055	SEED=`od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n'`
7056	make ... CFLAGS="-frandomize-layout-seed=$SEED" ...
7057
7058	You can also supply the seed in a file with ``-frandomize-layout-seed-file=``.
7059	For example:
7060
7061	.. code-block:: bash
7062
7063	od -A n -t x8 -N 32 /dev/urandom \| tr -d ' \n' > /tmp/seed_file.txt
7064	make ... CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt" ...
7065
7066	The randomization is deterministic based for a given seed, so the entire
7067	program should be compiled with the same seed, but keep the seed safe
7068	otherwise.
7069
7070	The attribute ``no_randomize_layout``, when attached to a C structure,
7071	instructs the compiler that this structure should not have its field layout
7072	randomized.)reST";
7073
7074	static const char AttrDoc_ReadOnlyPlacement[] = R"reST(This attribute is attached to a structure, class or union declaration.
7075	When attached to a record declaration/definition, it checks if all instances
7076	of this type can be placed in the read-only data segment of the program. If it
7077	finds an instance that can not be placed in a read-only segment, the compiler
7078	emits a warning at the source location where the type was used.
7079
7080	Examples:
7081	* ``struct __attribute__((enforce_read_only_placement)) Foo;``
7082	* ``struct __attribute__((enforce_read_only_placement)) Bar { ... };``
7083
7084	Both ``Foo`` and ``Bar`` types have the ``enforce_read_only_placement`` attribute.
7085
7086	The goal of introducing this attribute is to assist developers with writing secure
7087	code. A ``const``-qualified global is generally placed in the read-only section
7088	of the memory that has additional run time protection from malicious writes. By
7089	attaching this attribute to a declaration, the developer can express the intent
7090	to place all instances of the annotated type in the read-only program memory.
7091
7092	Note 1: The attribute doesn't guarantee that the object will be placed in the
7093	read-only data segment as it does not instruct the compiler to ensure such
7094	a placement. It emits a warning if something in the code can be proven to prevent
7095	an instance from being placed in the read-only data segment.
7096
7097	Note 2: Currently, clang only checks if all global declarations of a given type 'T'
7098	are ``const``-qualified. The following conditions would also prevent the data to be
7099	put into read only segment, but the corresponding warnings are not yet implemented.
7100
7101	1. An instance of type ``T`` is allocated on the heap/stack.
7102	2. Type ``T`` defines/inherits a mutable field.
7103	3. Type ``T`` defines/inherits non-constexpr constructor(s) for initialization.
7104	4. A field of type ``T`` is defined by type ``Q``, which does not bear the
7105	``enforce_read_only_placement`` attribute.
7106	5. A type ``Q`` inherits from type ``T`` and it does not have the
7107	``enforce_read_only_placement`` attribute.)reST";
7108
7109	static const char AttrDoc_ReentrantCapability[] = R"reST(No documentation.)reST";
7110
7111	static const char AttrDoc_RegCall[] = R"reST(On x86 targets, this attribute changes the calling convention to
7112	`__regcall`_ convention. This convention aims to pass as many arguments
7113	as possible in registers. It also tries to utilize registers for the
7114	return value whenever it is possible.
7115
7116	.. _`__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";
7117
7118	static const char AttrDoc_Reinitializes[] = R"reST(The ``reinitializes`` attribute can be applied to a non-static, non-const C++
7119	member function to indicate that this member function reinitializes the entire
7120	object to a known state, independent of the previous state of the object.
7121
7122	This attribute can be interpreted by static analyzers that warn about uses of an
7123	object that has been left in an indeterminate state by a move operation. If a
7124	member function marked with the ``reinitializes`` attribute is called on a
7125	moved-from object, the analyzer can conclude that the object is no longer in an
7126	indeterminate state.
7127
7128	A typical example where this attribute would be used is on functions that clear
7129	a container class:
7130
7131	.. code-block:: c++
7132
7133	template <class T>
7134	class Container {
7135	public:
7136	...
7137	[[clang::reinitializes]] void Clear();
7138	...
7139	};)reST";
7140
7141	static const char AttrDoc_ReleaseCapability[] = R"reST(Marks a function as releasing a capability.)reST";
7142
7143	static const char AttrDoc_ReleaseHandle[] = R"reST(If a function parameter is annotated with ``release_handle(tag)`` it is assumed to
7144	close the handle. It is also assumed to require an open handle to work with. The
7145	attribute requires a string literal argument to identify the handle being released.
7146
7147	.. code-block:: c++
7148
7149	zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle("tag")]]);)reST";
7150
7151	static const char AttrDoc_ReqdWorkGroupSize[] = R"reST(No documentation.)reST";
7152
7153	static const char AttrDoc_RequiresCapability[] = R"reST(No documentation.)reST";
7154
7155	static const char AttrDoc_Restrict[] = R"reST(The ``malloc`` attribute has two forms with different functionality. The first
7156	is when it is used without arguments, where it marks that a function acts like
7157	a system memory allocation function, returning a pointer to allocated storage
7158	that does not alias storage from any other object accessible to the caller.
7159
7160	The second form is when ``malloc`` takes one or two arguments. The first
7161	argument names a function that should be associated with this function as its
7162	deallocation function. When this form is used, it enables the compiler to
7163	diagnose when the incorrect deallocation function is used with this variable.
7164	However the associated warning, spelled `-Wmismatched-dealloc` in GCC, is not
7165	yet implemented in clang.)reST";
7166
7167	static const char AttrDoc_Retain[] = R"reST(This attribute, when attached to a function or variable definition, prevents
7168	section garbage collection in the linker. It does not prevent other discard
7169	mechanisms, such as archive member selection, and COMDAT group resolution.
7170
7171	If the compiler does not emit the definition, e.g. because it was not used in
7172	the translation unit or the compiler was able to eliminate all of the uses,
7173	this attribute has no effect. This attribute is typically combined with the
7174	``used`` attribute to force the definition to be emitted and preserved into the
7175	final linked image.
7176
7177	This attribute is only necessary on ELF targets; other targets prevent section
7178	garbage collection by the linker when using the ``used`` attribute alone.
7179	Using the attributes together should result in consistent behavior across
7180	targets.
7181
7182	This attribute requires the linker to support the ``SHF_GNU_RETAIN`` extension.
7183	This support is available in GNU ``ld`` and ``gold`` as of binutils 2.36, as
7184	well as in ``ld.lld`` 13.)reST";
7185
7186	static const char AttrDoc_ReturnTypestate[] = R"reST(The ``return_typestate`` attribute can be applied to functions or parameters.
7187	When applied to a function the attribute specifies the state of the returned
7188	value. The function's body is checked to ensure that it always returns a value
7189	in the specified state. On the caller side, values returned by the annotated
7190	function are initialized to the given state.
7191
7192	When applied to a function parameter it modifies the state of an argument after
7193	a call to the function returns. The function's body is checked to ensure that
7194	the parameter is in the expected state before returning.)reST";
7195
7196	static const char AttrDoc_ReturnsNonNull[] = R"reST(The ``returns_nonnull`` attribute indicates that a particular function (or
7197	Objective-C method) always returns a non-null pointer. For example, a
7198	particular system ``malloc`` might be defined to terminate a process when
7199	memory is not available rather than returning a null pointer:
7200
7201	.. code-block:: c
7202
7203	extern void * malloc (size_t size) __attribute__((returns_nonnull));
7204
7205	The ``returns_nonnull`` attribute implies that returning a null pointer is
7206	undefined behavior, which the optimizer may take advantage of. The ``_Nonnull``
7207	type qualifier indicates that a pointer cannot be null in a more general manner
7208	(because it is part of the type system) and does not imply undefined behavior,
7209	making it more widely applicable)reST";
7210
7211	static const char AttrDoc_ReturnsTwice[] = R"reST(No documentation.)reST";
7212
7213	static const char AttrDoc_RootSignature[] = R"reST(The ``RootSignature`` attribute applies to HLSL entry functions to define what
7214	types of resources are bound to the graphics pipeline.
7215
7216	For details about the use and specification of Root Signatures please see here:
7217	https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signatures)reST";
7218
7219	static const char AttrDoc_SPtr[] = R"reST(The ``__sptr`` qualifier specifies that a 32-bit pointer should be sign
7220	extended when converted to a 64-bit pointer.)reST";
7221
7222	static const char AttrDoc_SYCLExternal[] = R"reST(The ``sycl_external`` attribute indicates that a function defined in another
7223	translation unit may be called by a device function defined in the current
7224	translation unit or, if defined in the current translation unit, the function
7225	may be called by device functions defined in other translation units.
7226	The attribute is intended for use in the implementation of the ``SYCL_EXTERNAL``
7227	macro as specified in section 5.10.1, "SYCL functions and member functions
7228	linkage", of the SYCL 2020 specification.
7229
7230	The attribute only appertains to functions and only those that meet the
7231	following requirements:
7232
7233	* Has external linkage
7234	* Is not explicitly defined as deleted (the function may be an explicitly
7235	defaulted function that is defined as deleted)
7236
7237	The attribute shall be present on the first declaration of a function and
7238	may optionally be present on subsequent declarations.
7239
7240	When compiling for a SYCL device target that does not support the generic
7241	address space, the function shall not specify a raw pointer or reference type
7242	as the return type or as a parameter type.
7243	See section 5.10, "SYCL offline linking", of the SYCL 2020 specification.
7244	The following examples demonstrate the use of this attribute:
7245
7246	.. code-block:: c++
7247
7248	[[clang::sycl_external]] void Foo(); // Ok.
7249
7250	[[clang::sycl_external]] void Bar() { /* ... */ } // Ok.
7251
7252	[[clang::sycl_external]] extern void Baz(); // Ok.
7253
7254	[[clang::sycl_external]] static void Quux() { /* ... */ } // error: Quux() has internal linkage.)reST";
7255
7256	static const char AttrDoc_SYCLKernel[] = R"reST(The ``sycl_kernel`` attribute specifies that a function template will be used
7257	to outline device code and to generate an OpenCL kernel.
7258	Here is a code example of the SYCL program, which demonstrates the compiler's
7259	outlining job:
7260
7261	.. code-block:: c++
7262
7263	int foo(int x) { return ++x; }
7264
7265	using namespace cl::sycl;
7266	queue Q;
7267	buffer<int, 1> a(range<1>{1024});
7268	Q.submit([&](handler& cgh) {
7269	auto A = a.get_access<access::mode::write>(cgh);
7270	cgh.parallel_for<init_a>(range<1>{1024}, [=](id<1> index) {
7271	A[index] = index[0] + foo(42);
7272	});
7273	}
7274
7275	A C++ function object passed to the ``parallel_for`` is called a "SYCL kernel".
7276	A SYCL kernel defines the entry point to the "device part" of the code. The
7277	compiler will emit all symbols accessible from a "kernel". In this code
7278	example, the compiler will emit "foo" function. More details about the
7279	compilation of functions for the device part can be found in the SYCL 1.2.1
7280	specification Section 6.4.
7281	To show to the compiler entry point to the "device part" of the code, the SYCL
7282	runtime can use the ``sycl_kernel`` attribute in the following way:
7283
7284	.. code-block:: c++
7285
7286	namespace cl {
7287	namespace sycl {
7288	class handler {
7289	template <typename KernelName, typename KernelType/, .../>
7290	__attribute__((sycl_kernel)) void sycl_kernel_function(KernelType KernelFuncObj) {
7291	// ...
7292	KernelFuncObj();
7293	}
7294
7295	template <typename KernelName, typename KernelType, int Dims>
7296	void parallel_for(range<Dims> NumWorkItems, KernelType KernelFunc) {
7297	#ifdef __SYCL_DEVICE_ONLY__
7298	sycl_kernel_function<KernelName, KernelType, Dims>(KernelFunc);
7299	#else
7300	// Host implementation
7301	#endif
7302	}
7303	};
7304	} // namespace sycl
7305	} // namespace cl
7306
7307	The compiler will also generate an OpenCL kernel using the function marked with
7308	the ``sycl_kernel`` attribute.
7309	Here is the list of SYCL device compiler expectations with regard to the
7310	function marked with the ``sycl_kernel`` attribute:
7311
7312	- The function must be a template with at least two type template parameters.
7313	The compiler generates an OpenCL kernel and uses the first template parameter
7314	as a unique name for the generated OpenCL kernel. The host application uses
7315	this unique name to invoke the OpenCL kernel generated for the SYCL kernel
7316	specialized by this name and second template parameter ``KernelType`` (which
7317	might be an unnamed function object type).
7318	- The function must have at least one parameter. The first parameter is
7319	required to be a function object type (named or unnamed i.e. lambda). The
7320	compiler uses function object type fields to generate OpenCL kernel
7321	parameters.
7322	- The function must return void. The compiler reuses the body of marked functions to
7323	generate the OpenCL kernel body, and the OpenCL kernel must return ``void``.
7324
7325	The SYCL kernel in the previous code sample meets these expectations.)reST";
7326
7327	static const char AttrDoc_SYCLKernelEntryPoint[] = R"reST(The ``sycl_kernel_entry_point`` attribute facilitates the generation of an
7328	offload kernel entry point, sometimes called a SYCL kernel caller function,
7329	suitable for invoking a SYCL kernel on an offload device. The attribute is
7330	intended for use in the implementation of SYCL kernel invocation functions
7331	like the ``single_task`` and ``parallel_for`` member functions of the
7332	``sycl::handler`` class specified in section 4.9.4, "Command group ``handler``
7333	class", of the SYCL 2020 specification.
7334
7335	The attribute requires a single type argument that specifies a class type that
7336	meets the requirements for a SYCL kernel name as described in section 5.2,
7337	"Naming of kernels", of the SYCL 2020 specification. A unique kernel name type
7338	is required for each function declared with the attribute. The attribute may
7339	not first appear on a declaration that follows a definition of the function.
7340
7341	The attribute only appertains to functions and only those that meet the
7342	following requirements.
7343
7344	* Has a non-deduced ``void`` return type.
7345	* Is not a non-static member function, constructor, or destructor.
7346	* Is not a C variadic function.
7347	* Is not a coroutine.
7348	* Is not defined as deleted or as defaulted.
7349	* Is not defined with a function try block.
7350	* Is not declared with the ``constexpr`` or ``consteval`` specifiers.
7351	* Is not declared with the ``[[noreturn]]`` attribute.
7352
7353	Use in the implementation of a SYCL kernel invocation function might look as
7354	follows.
7355
7356	.. code-block:: c++
7357
7358	namespace sycl {
7359	class handler {
7360	template<typename KernelNameType, typename KernelType>
7361	[[ clang::sycl_kernel_entry_point(KernelNameType) ]]
7362	static void kernel_entry_point(KernelType kernel) {
7363	kernel();
7364	}
7365
7366	public:
7367	template<typename KernelNameType, typename KernelType>
7368	void single_task(KernelType kernel) {
7369	// Call kernel_entry_point() to trigger generation of an offload
7370	// kernel entry point.
7371	kernel_entry_point<KernelNameType>(kernel);
7372	// Call functions appropriate for the desired offload backend
7373	// (OpenCL, CUDA, HIP, Level Zero, etc...).
7374	}
7375	};
7376	} // namespace sycl
7377
7378	A SYCL kernel is a callable object of class type that is constructed on a host,
7379	often via a lambda expression, and then passed to a SYCL kernel invocation
7380	function to be executed on an offload device. A SYCL kernel invocation function
7381	is responsible for copying the provided SYCL kernel object to an offload
7382	device and initiating a call to it. The SYCL kernel object and its data members
7383	constitute the parameters of an offload kernel.
7384
7385	A SYCL kernel type is required to satisfy the device copyability requirements
7386	specified in section 3.13.1, "Device copyable", of the SYCL 2020 specification.
7387	Additionally, any data members of the kernel object type are required to satisfy
7388	section 4.12.4, "Rules for parameter passing to kernels". For most types, these
7389	rules require that the type is trivially copyable. However, the SYCL
7390	specification mandates that certain special SYCL types, such as
7391	``sycl::accessor`` and ``sycl::stream`` be device copyable even if they are not
7392	trivially copyable. These types require special handling because they cannot
7393	be copied to device memory as if by ``memcpy()``. Additionally, some offload
7394	backends, OpenCL for example, require objects of some of these types to be
7395	passed as individual arguments to the offload kernel.
7396
7397	An offload kernel consists of an entry point function that declares the
7398	parameters of the offload kernel and the set of all functions and variables that
7399	are directly or indirectly used by the entry point function.
7400
7401	A SYCL kernel invocation function invokes a SYCL kernel on a device by
7402	performing the following tasks (likely with the help of an offload backend
7403	like OpenCL):
7404
7405	#. Identifying the offload kernel entry point to be used for the SYCL kernel.
7406
7407	#. Deconstructing the SYCL kernel object, if necessary, to produce the set of
7408	offload kernel arguments required by the offload kernel entry point.
7409
7410	#. Copying the offload kernel arguments to device memory.
7411
7412	#. Initiating execution of the offload kernel entry point.
7413
7414	The offload kernel entry point for a SYCL kernel performs the following tasks:
7415
7416	#. Reconstituting the SYCL kernel object, if necessary, using the offload
7417	kernel parameters.
7418
7419	#. Calling the ``operator()`` member function of the (reconstituted) SYCL kernel
7420	object.
7421
7422	The ``sycl_kernel_entry_point`` attribute automates generation of an offload
7423	kernel entry point that performs those latter tasks. The parameters and body of
7424	a function declared with the ``sycl_kernel_entry_point`` attribute specify a
7425	pattern from which the parameters and body of the entry point function are
7426	derived. Consider the following call to a SYCL kernel invocation function.
7427
7428	.. code-block:: c++
7429
7430	struct S { int i; };
7431	void f(sycl::handler &handler, sycl::stream &sout, S s) {
7432	handler.single_task<struct KN>([=] {
7433	sout << "The value of s.i is " << s.i << "\n";
7434	});
7435	}
7436
7437	The SYCL kernel object is the result of the lambda expression. It has two
7438	data members corresponding to the captures of ``sout`` and ``s``. Since one
7439	of these data members corresponds to a special SYCL type that must be passed
7440	individually as an offload kernel parameter, it is necessary to decompose the
7441	SYCL kernel object into its constituent parts; the offload kernel will have
7442	two kernel parameters. Given a SYCL implementation that uses a
7443	``sycl_kernel_entry_point`` attributed function like the one shown above, an
7444	offload kernel entry point function will be generated that looks approximately
7445	as follows.
7446
7447	.. code-block:: c++
7448
7449	void sycl-kernel-caller-for-KN(sycl::stream sout, S s) {
7450	kernel-type kernel = { sout, s );
7451	kernel();
7452	}
7453
7454	There are a few items worthy of note:
7455
7456	#. The name of the generated function incorporates the SYCL kernel name,
7457	``KN``, that was passed as the ``KernelNameType`` template parameter to
7458	``kernel_entry_point()`` and provided as the argument to the
7459	``sycl_kernel_entry_point`` attribute. There is a one-to-one correspondence
7460	between SYCL kernel names and offload kernel entry points.
7461
7462	#. The SYCL kernel is a lambda closure type and therefore has no name;
7463	``kernel-type`` is substituted above and corresponds to the ``KernelType``
7464	template parameter deduced in the call to ``kernel_entry_point()``.
7465	Lambda types cannot be declared and initialized using the aggregate
7466	initialization syntax used above, but the intended behavior should be clear.
7467
7468	#. ``S`` is a device copyable type that does not directly or indirectly contain
7469	a data member of a SYCL special type. It therefore does not need to be
7470	decomposed into its constituent members to be passed as a kernel argument.
7471
7472	#. The depiction of the ``sycl::stream`` parameter as a single self contained
7473	kernel parameter is an oversimplification. SYCL special types may require
7474	additional decomposition such that the generated function might have three
7475	or more parameters depending on how the SYCL library implementation defines
7476	these types.
7477
7478	#. The call to ``kernel_entry_point()`` has no effect other than to trigger
7479	emission of the entry point function. The statments that make up the body
7480	of the function are not executed when the function is called; they are
7481	only used in the generation of the entry point function.
7482
7483	It is not necessary for a function declared with the ``sycl_kernel_entry_point``
7484	attribute to be called for the offload kernel entry point to be emitted. For
7485	inline functions and function templates, any ODR-use will suffice. For other
7486	functions, an ODR-use is not required; the offload kernel entry point will be
7487	emitted if the function is defined.
7488
7489	Functions declared with the ``sycl_kernel_entry_point`` attribute are not
7490	limited to the simple example shown above. They may have additional template
7491	parameters, declare additional function parameters, and have complex control
7492	flow in the function body. Function parameter decomposition and reconstitution
7493	is performed for all function parameters. The function must abide by the
7494	language feature restrictions described in section 5.4, "Language restrictions
7495	for device functions" in the SYCL 2020 specification.)reST";
7496
7497	static const char AttrDoc_SYCLSpecialClass[] = R"reST(SYCL defines some special classes (accessor, sampler, and stream) which require
7498	specific handling during the generation of the SPIR entry point.
7499	The ``__attribute__((sycl_special_class))`` attribute is used in SYCL
7500	headers to indicate that a class or a struct needs a specific handling when
7501	it is passed from host to device.
7502	Special classes will have a mandatory ``__init`` method and an optional
7503	``__finalize`` method (the ``__finalize`` method is used only with the
7504	``stream`` type). Kernel parameters types are extract from the ``__init`` method
7505	parameters. The kernel function arguments list is derived from the
7506	arguments of the ``__init`` method. The arguments of the ``__init`` method are
7507	copied into the kernel function argument list and the ``__init`` and
7508	``__finalize`` methods are called at the beginning and the end of the kernel,
7509	respectively.
7510	The ``__init`` and ``__finalize`` methods must be defined inside the
7511	special class.
7512	Please note that this is an attribute that is used as an internal
7513	implementation detail and not intended to be used by external users.
7514
7515	The syntax of the attribute is as follows:
7516
7517	.. code-block:: text
7518
7519	class __attribute__((sycl_special_class)) accessor {};
7520	class [[clang::sycl_special_class]] accessor {};
7521
7522	This is a code example that illustrates the use of the attribute:
7523
7524	.. code-block:: c++
7525
7526	class __attribute__((sycl_special_class)) SpecialType {
7527	int F1;
7528	int F2;
7529	void __init(int f1) {
7530	F1 = f1;
7531	F2 = f1;
7532	}
7533	void __finalize() {}
7534	public:
7535	SpecialType() = default;
7536	int getF2() const { return F2; }
7537	};
7538
7539	int main () {
7540	SpecialType T;
7541	cgh.single_task([=] {
7542	T.getF2();
7543	});
7544	}
7545
7546	This would trigger the following kernel entry point in the AST:
7547
7548	.. code-block:: c++
7549
7550	void __sycl_kernel(int f1) {
7551	SpecialType T;
7552	T.__init(f1);
7553	...
7554	T.__finalize()
7555	})reST";
7556
7557	static const char AttrDoc_ScopedLockable[] = R"reST(No documentation.)reST";
7558
7559	static const char AttrDoc_Section[] = R"reST(The ``section`` attribute allows you to specify a specific section a
7560	global variable or function should be in after translation.)reST";
7561
7562	static const char AttrDoc_SelectAny[] = R"reST(This attribute appertains to a global symbol, causing it to have a weak
7563	definition (
7564	`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
7565	), allowing the linker to select any definition.
7566
7567	For more information see
7568	`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
7569	or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.)reST";
7570
7571	static const char AttrDoc_Sentinel[] = R"reST(No documentation.)reST";
7572
7573	static const char AttrDoc_SetTypestate[] = R"reST(Annotate methods that transition an object into a new state with
7574	``__attribute__((set_typestate(new_state)))``. The new state must be
7575	unconsumed, consumed, or unknown.)reST";
7576
7577	static const char AttrDoc_SizedBy[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
7578	structure in C. The argument for the attribute is the name of a field member
7579	holding the count of elements in the flexible array. This information can be
7580	used to improve the results of the array bound sanitizer and the
7581	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
7582	within the same non-anonymous, enclosing struct as the flexible array member.
7583
7584	This example specifies that the flexible array member ``array`` has the number
7585	of elements allocated for it in ``count``:
7586
7587	.. code-block:: c
7588
7589	struct bar;
7590
7591	struct foo {
7592	size_t count;
7593	char other;
7594	struct bar *array[] __attribute__((counted_by(count)));
7595	};
7596
7597	This establishes a relationship between ``array`` and ``count``. Specifically,
7598	``array`` must have at least ``count`` number of elements available. It's the
7599	user's responsibility to ensure that this relationship is maintained through
7600	changes to the structure.
7601
7602	In the following example, the allocated array erroneously has fewer elements
7603	than what's specified by ``p->count``. This would result in an out-of-bounds
7604	access not being detected.
7605
7606	.. code-block:: c
7607
7608	#define SIZE_INCR 42
7609
7610	struct foo *p;
7611
7612	void foo_alloc(size_t count) {
7613	p = malloc(MAX(sizeof(struct foo),
7614	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7615	p->count = count + SIZE_INCR;
7616	}
7617
7618	The next example updates ``p->count``, but breaks the relationship requirement
7619	that ``p->array`` must have at least ``p->count`` number of elements available:
7620
7621	.. code-block:: c
7622
7623	#define SIZE_INCR 42
7624
7625	struct foo *p;
7626
7627	void foo_alloc(size_t count) {
7628	p = malloc(MAX(sizeof(struct foo),
7629	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7630	p->count = count;
7631	}
7632
7633	void use_foo(int index, int val) {
7634	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
7635	p->array[index] = val; /* The sanitizer can't properly check this access. */
7636	}
7637
7638	In this example, an update to ``p->count`` maintains the relationship
7639	requirement:
7640
7641	.. code-block:: c
7642
7643	void use_foo(int index, int val) {
7644	if (p->count == 0)
7645	return;
7646	--p->count;
7647	p->array[index] = val;
7648	})reST";
7649
7650	static const char AttrDoc_SizedByOrNull[] = R"reST(Clang supports the ``counted_by`` attribute on the flexible array member of a
7651	structure in C. The argument for the attribute is the name of a field member
7652	holding the count of elements in the flexible array. This information can be
7653	used to improve the results of the array bound sanitizer and the
7654	``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
7655	within the same non-anonymous, enclosing struct as the flexible array member.
7656
7657	This example specifies that the flexible array member ``array`` has the number
7658	of elements allocated for it in ``count``:
7659
7660	.. code-block:: c
7661
7662	struct bar;
7663
7664	struct foo {
7665	size_t count;
7666	char other;
7667	struct bar *array[] __attribute__((counted_by(count)));
7668	};
7669
7670	This establishes a relationship between ``array`` and ``count``. Specifically,
7671	``array`` must have at least ``count`` number of elements available. It's the
7672	user's responsibility to ensure that this relationship is maintained through
7673	changes to the structure.
7674
7675	In the following example, the allocated array erroneously has fewer elements
7676	than what's specified by ``p->count``. This would result in an out-of-bounds
7677	access not being detected.
7678
7679	.. code-block:: c
7680
7681	#define SIZE_INCR 42
7682
7683	struct foo *p;
7684
7685	void foo_alloc(size_t count) {
7686	p = malloc(MAX(sizeof(struct foo),
7687	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7688	p->count = count + SIZE_INCR;
7689	}
7690
7691	The next example updates ``p->count``, but breaks the relationship requirement
7692	that ``p->array`` must have at least ``p->count`` number of elements available:
7693
7694	.. code-block:: c
7695
7696	#define SIZE_INCR 42
7697
7698	struct foo *p;
7699
7700	void foo_alloc(size_t count) {
7701	p = malloc(MAX(sizeof(struct foo),
7702	offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
7703	p->count = count;
7704	}
7705
7706	void use_foo(int index, int val) {
7707	p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
7708	p->array[index] = val; /* The sanitizer can't properly check this access. */
7709	}
7710
7711	In this example, an update to ``p->count`` maintains the relationship
7712	requirement:
7713
7714	.. code-block:: c
7715
7716	void use_foo(int index, int val) {
7717	if (p->count == 0)
7718	return;
7719	--p->count;
7720	p->array[index] = val;
7721	})reST";
7722
7723	static const char AttrDoc_SpeculativeLoadHardening[] = R"reST(This attribute can be applied to a function declaration in order to indicate
7724	that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
7725	should be enabled for the function body. This can also be applied to a method
7726	in Objective C. This attribute will take precedence over the command line flag in
7727	the case where `-mno-speculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
7728
7729	Speculative Load Hardening is a best-effort mitigation against
7730	information leak attacks that make use of control flow
7731	miss-speculation - specifically miss-speculation of whether a branch
7732	is taken or not. Typically vulnerabilities enabling such attacks are
7733	classified as "Spectre variant #1". Notably, this does not attempt to
7734	mitigate against miss-speculation of branch target, classified as
7735	"Spectre variant #2" vulnerabilities.
7736
7737	When inlining, the attribute is sticky. Inlining a function that
7738	carries this attribute will cause the caller to gain the
7739	attribute. This is intended to provide a maximally conservative model
7740	where the code in a function annotated with this attribute will always
7741	(even after inlining) end up hardened.)reST";
7742
7743	static const char AttrDoc_StackProtectorIgnore[] = R"reST(The ``stack_protector_ignore`` attribute skips analysis of the given local
7744	variable when determining if a function should use a stack protector.
7745
7746	The ``-fstack-protector`` option uses a heuristic to only add stack protectors
7747	to functions which contain variables or buffers over some size threshold. This
7748	attribute overrides that heuristic for the attached variable, opting
7749	them out. If this results in no variables or buffers remaining over the stack
7750	protector threshold, then the function will no longer use a stack protector.)reST";
7751
7752	static const char AttrDoc_StandaloneDebug[] = R"reST(The ``standalone_debug`` attribute causes debug info to be emitted for a record
7753	type regardless of the debug info optimizations that are enabled with
7754	-fno-standalone-debug. This attribute only has an effect when debug info
7755	optimizations are enabled (e.g. with -fno-standalone-debug), and is C++-only.)reST";
7756
7757	static const char AttrDoc_StdCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
7758	function to clear parameters off of the stack on return. This convention does
7759	not support variadic calls or unprototyped functions in C, and has no effect on
7760	x86_64 targets. This calling convention is used widely by the Windows API and
7761	COM applications. See the documentation for `__stdcall`_ on MSDN.
7762
7763	.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx)reST";
7764
7765	static const char AttrDoc_StrictFP[] = R"reST()reST";
7766
7767	static const char AttrDoc_StrictGuardStackCheck[] = R"reST(Clang supports the Microsoft style ``__declspec((strict_gs_check))`` attribute
7768	which upgrades the stack protector check from ``-fstack-protector`` to
7769	``-fstack-protector-strong``.
7770
7771	For example, it upgrades the stack protector for the function ``foo`` to
7772	``-fstack-protector-strong`` but function ``bar`` will still be built with the
7773	stack protector with the ``-fstack-protector`` option.
7774
7775	.. code-block:: c
7776
7777	__declspec((strict_gs_check))
7778	int foo(int x); // stack protection will be upgraded for foo.
7779
7780	int bar(int y); // bar can be built with the standard stack protector checks.)reST";
7781
7782	static const char AttrDoc_Suppress[] = R"reST(The ``suppress`` attribute suppresses unwanted warnings coming from static
7783	analysis tools such as the Clang Static Analyzer. The tool will not report
7784	any issues in source code annotated with the attribute.
7785
7786	The attribute cannot be used to suppress traditional Clang warnings, because
7787	many such warnings are emitted before the attribute is fully parsed.
7788	Consider using ``#pragma clang diagnostic`` to control such diagnostics,
7789	as described in `Controlling Diagnostics via Pragmas
7790	<https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas>`_.
7791
7792	The ``suppress`` attribute can be placed on an individual statement in order to
7793	suppress warnings about undesirable behavior occurring at that statement:
7794
7795	.. code-block:: c++
7796
7797	int foo() {
7798	int *x = nullptr;
7799	...
7800	[[clang::suppress]]
7801	return *x; // null pointer dereference warning suppressed here
7802	}
7803
7804	Putting the attribute on a compound statement suppresses all warnings in scope:
7805
7806	.. code-block:: c++
7807
7808	int foo() {
7809	[[clang::suppress]] {
7810	int *x = nullptr;
7811	...
7812	return *x; // warnings suppressed in the entire scope
7813	}
7814	}
7815
7816	The attribute can also be placed on entire declarations of functions, classes,
7817	variables, member variables, and so on, to suppress warnings related
7818	to the declarations themselves. When used this way, the attribute additionally
7819	suppresses all warnings in the lexical scope of the declaration:
7820
7821	.. code-block:: c++
7822
7823	class [[clang::suppress]] C {
7824	int foo() {
7825	int *x = nullptr;
7826	...
7827	return *x; // warnings suppressed in the entire class scope
7828	}
7829
7830	int bar();
7831	};
7832
7833	int C::bar() {
7834	int *x = nullptr;
7835	...
7836	return *x; // warning NOT suppressed! - not lexically nested in 'class C{}'
7837	}
7838
7839	Some static analysis warnings are accompanied by one or more notes, and the
7840	line of code against which the warning is emitted isn't necessarily the best
7841	for suppression purposes. In such cases the tools are allowed to implement
7842	additional ways to suppress specific warnings based on the attribute attached
7843	to a note location.
7844
7845	For example, the Clang Static Analyzer suppresses memory leak warnings when
7846	the suppression attribute is placed at the allocation site (highlited by
7847	a "note: memory is allocated"), which may be different from the line of code
7848	at which the program "loses track" of the pointer (where the warning
7849	is ultimately emitted):
7850
7851	.. code-block:: c
7852
7853	int bar1(bool coin_flip) {
7854	__attribute__((suppress))
7855	int result = (int )malloc(sizeof(int));
7856	if (coin_flip)
7857	return 1; // warning about this leak path is suppressed
7858
7859	return *result; // warning about this leak path is also suppressed
7860	}
7861
7862	int bar2(bool coin_flip) {
7863	int result = (int )malloc(sizeof(int));
7864	if (coin_flip)
7865	return 1; // leak warning on this path NOT suppressed
7866
7867	__attribute__((suppress))
7868	return *result; // leak warning is suppressed only on this path
7869	}
7870
7871
7872	When written as ``[[gsl::suppress]]``, this attribute suppresses specific
7873	clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
7874	way. The attribute can be attached to declarations, statements, and at
7875	namespace scope.
7876
7877	.. code-block:: c++
7878
7879	[[gsl::suppress("Rh-public")]]
7880	void f_() {
7881	int *p;
7882	[[gsl::suppress("type")]] {
7883	p = reinterpret_cast<int*>(7);
7884	}
7885	}
7886	namespace N {
7887	[[clang::suppress("type", "bounds")]];
7888	...
7889	}
7890
7891	.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement)reST";
7892
7893	static const char AttrDoc_SwiftAsync[] = R"reST(The ``swift_async`` attribute specifies if and how a particular function or
7894	Objective-C method is imported into a swift async method. For instance:
7895
7896	.. code-block:: objc
7897
7898	@interface MyClass : NSObject
7899	-(void)notActuallyAsync:(int)p1 withCompletionHandler:(void (^)())handler
7900	__attribute__((swift_async(none)));
7901
7902	-(void)actuallyAsync:(int)p1 callThisAsync:(void (^)())fun
7903	__attribute__((swift_async(swift_private, 1)));
7904	@end
7905
7906	Here, ``notActuallyAsync:withCompletionHandler`` would have been imported as
7907	``async`` (because it's last parameter's selector piece is
7908	``withCompletionHandler``) if not for the ``swift_async(none)`` attribute.
7909	Conversely, ``actuallyAsync:callThisAsync`` wouldn't have been imported as
7910	``async`` if not for the ``swift_async`` attribute because it doesn't match the
7911	naming convention.
7912
7913	When using ``swift_async`` to enable importing, the first argument to the
7914	attribute is either ``swift_private`` or ``not_swift_private`` to indicate
7915	whether the function/method is private to the current framework, and the second
7916	argument is the index of the completion handler parameter.)reST";
7917
7918	static const char AttrDoc_SwiftAsyncCall[] = R"reST(The ``swiftasynccall`` attribute indicates that a function is
7919	compatible with the low-level conventions of Swift async functions,
7920	provided it declares the right formal arguments.
7921
7922	In most respects, this is similar to the ``swiftcall`` attribute, except for
7923	the following:
7924
7925	- A parameter may be marked ``swift_async_context``, ``swift_context``
7926	or ``swift_indirect_result`` (with the same restrictions on parameter
7927	ordering as ``swiftcall``) but the parameter attribute
7928	``swift_error_result`` is not permitted.
7929
7930	- A ``swiftasynccall`` function must have return type ``void``.
7931
7932	- Within a ``swiftasynccall`` function, a call to a ``swiftasynccall``
7933	function that is the immediate operand of a ``return`` statement is
7934	guaranteed to be performed as a tail call. This syntax is allowed even
7935	in C as an extension (a call to a void-returning function cannot be a
7936	return operand in standard C). If something in the calling function would
7937	semantically be performed after a guaranteed tail call, such as the
7938	non-trivial destruction of a local variable or temporary,
7939	then the program is ill-formed.
7940
7941	Query for this attribute with ``__has_attribute(swiftasynccall)``. Query if
7942	the target supports the calling convention with
7943	``__has_extension(swiftasynccc)``.)reST";
7944
7945	static const char AttrDoc_SwiftAsyncContext[] = R"reST(The ``swift_async_context`` attribute marks a parameter of a ``swiftasynccall``
7946	function as having the special asynchronous context-parameter ABI treatment.
7947
7948	If the function is not ``swiftasynccall``, this attribute only generates
7949	extended frame information.
7950
7951	A context parameter must have pointer or reference type.)reST";
7952
7953	static const char AttrDoc_SwiftAsyncError[] = R"reST(The ``swift_async_error`` attribute specifies how an error state will be
7954	represented in a swift async method. It's a bit analogous to the ``swift_error``
7955	attribute for the generated async method. The ``swift_async_error`` attribute
7956	can indicate a variety of different ways of representing an error.
7957
7958	- ``__attribute__((swift_async_error(zero_argument, N)))``, specifies that the
7959	async method is considered to have failed if the Nth argument to the
7960	completion handler is zero.
7961
7962	- ``__attribute__((swift_async_error(nonzero_argument, N)))``, specifies that
7963	the async method is considered to have failed if the Nth argument to the
7964	completion handler is non-zero.
7965
7966	- ``__attribute__((swift_async_error(nonnull_error)))``, specifies that the
7967	async method is considered to have failed if the ``NSError *`` argument to the
7968	completion handler is non-null.
7969
7970	- ``__attribute__((swift_async_error(none)))``, specifies that the async method
7971	cannot fail.
7972
7973
7974	For instance:
7975
7976	.. code-block:: objc
7977
7978	@interface MyClass : NSObject
7979	-(void)asyncMethod:(void (^)(char, int, float))handler
7980	__attribute__((swift_async(swift_private, 1)))
7981	__attribute__((swift_async_error(zero_argument, 2)));
7982	@end
7983
7984	Here, the ``swift_async`` attribute specifies that ``handler`` is the completion
7985	handler for this method, and the ``swift_async_error`` attribute specifies that
7986	the ``int`` parameter is the one that represents the error.)reST";
7987
7988	static const char AttrDoc_SwiftAsyncName[] = R"reST(The ``swift_async_name`` attribute provides the name of the ``async`` overload for
7989	the given declaration in Swift. If this attribute is absent, the name is
7990	transformed according to the algorithm built into the Swift compiler.
7991
7992	The argument is a string literal that contains the Swift name of the function or
7993	method. The name may be a compound Swift name. The function or method with such
7994	an attribute must have more than zero parameters, as its last parameter is
7995	assumed to be a callback that's eliminated in the Swift ``async`` name.
7996
7997	.. code-block:: objc
7998
7999	@interface URL
8000	+ (void) loadContentsFrom:(URL )url callback:(void (^)(NSData ))data __attribute__((__swift_async_name__("URL.loadContentsFrom(_:)")))
8001	@end)reST";
8002
8003	static const char AttrDoc_SwiftAttr[] = R"reST(The ``swift_attr`` provides a Swift-specific annotation for the declaration
8004	or type to which the attribute appertains to. It can be used on any declaration
8005	or type in Clang. This kind of annotation is ignored by Clang as it doesn't have any
8006	semantic meaning in languages supported by Clang. The Swift compiler can
8007	interpret these annotations according to its own rules when importing C or
8008	Objective-C declarations.)reST";
8009
8010	static const char AttrDoc_SwiftBridge[] = R"reST(The ``swift_bridge`` attribute indicates that the declaration to which the
8011	attribute appertains is bridged to the named Swift type.
8012
8013	.. code-block:: objc
8014
8015	__attribute__((__objc_root__))
8016	@interface Base
8017	- (instancetype)init;
8018	@end
8019
8020	__attribute__((__swift_bridge__("BridgedI")))
8021	@interface I : Base
8022	@end
8023
8024	In this example, the Objective-C interface ``I`` will be made available to Swift
8025	with the name ``BridgedI``. It would be possible for the compiler to refer to
8026	``I`` still in order to bridge the type back to Objective-C.)reST";
8027
8028	static const char AttrDoc_SwiftBridgedTypedef[] = R"reST(The ``swift_bridged_typedef`` attribute indicates that when the typedef to which
8029	the attribute appertains is imported into Swift, it should refer to the bridged
8030	Swift type (e.g. Swift's ``String``) rather than the Objective-C type as written
8031	(e.g. ``NSString``).
8032
8033	.. code-block:: objc
8034
8035	@interface NSString;
8036	typedef NSString *AliasedString __attribute__((__swift_bridged_typedef__));
8037
8038	extern void acceptsAliasedString(AliasedString _Nonnull parameter);
8039
8040	In this case, the function ``acceptsAliasedString`` will be imported into Swift
8041	as a function which accepts a ``String`` type parameter.)reST";
8042
8043	static const char AttrDoc_SwiftCall[] = R"reST(The ``swiftcall`` attribute indicates that a function should be called
8044	using the Swift calling convention for a function or function pointer.
8045
8046	The lowering for the Swift calling convention, as described by the Swift
8047	ABI documentation, occurs in multiple phases. The first, "high-level"
8048	phase breaks down the formal parameters and results into innately direct
8049	and indirect components, adds implicit parameters for the generic
8050	signature, and assigns the context and error ABI treatments to parameters
8051	where applicable. The second phase breaks down the direct parameters
8052	and results from the first phase and assigns them to registers or the
8053	stack. The ``swiftcall`` convention only handles this second phase of
8054	lowering; the C function type must accurately reflect the results
8055	of the first phase, as follows:
8056
8057	- Results classified as indirect by high-level lowering should be
8058	represented as parameters with the ``swift_indirect_result`` attribute.
8059
8060	- Results classified as direct by high-level lowering should be represented
8061	as follows:
8062
8063	- First, remove any empty direct results.
8064
8065	- If there are no direct results, the C result type should be ``void``.
8066
8067	- If there is one direct result, the C result type should be a type with
8068	the exact layout of that result type.
8069
8070	- If there are a multiple direct results, the C result type should be
8071	a struct type with the exact layout of a tuple of those results.
8072
8073	- Parameters classified as indirect by high-level lowering should be
8074	represented as parameters of pointer type.
8075
8076	- Parameters classified as direct by high-level lowering should be
8077	omitted if they are empty types; otherwise, they should be represented
8078	as a parameter type with a layout exactly matching the layout of the
8079	Swift parameter type.
8080
8081	- The context parameter, if present, should be represented as a trailing
8082	parameter with the ``swift_context`` attribute.
8083
8084	- The error result parameter, if present, should be represented as a
8085	trailing parameter (always following a context parameter) with the
8086	``swift_error_result`` attribute.
8087
8088	``swiftcall`` does not support variadic arguments or unprototyped functions.
8089
8090	The parameter ABI treatment attributes are aspects of the function type.
8091	A function type which applies an ABI treatment attribute to a
8092	parameter is a different type from an otherwise-identical function type
8093	that does not. A single parameter may not have multiple ABI treatment
8094	attributes.
8095
8096	Support for this feature is target-dependent, although it should be
8097	supported on every target that Swift supports. Query for this attribute
8098	with ``__has_attribute(swiftcall)``. Query if the target supports the
8099	calling convention with ``__has_extension(swiftcc)``. This implies
8100	support for the ``swift_context``, ``swift_error_result``, and
8101	``swift_indirect_result`` attributes.)reST";
8102
8103	static const char AttrDoc_SwiftContext[] = R"reST(The ``swift_context`` attribute marks a parameter of a ``swiftcall``
8104	or ``swiftasynccall`` function as having the special context-parameter
8105	ABI treatment.
8106
8107	This treatment generally passes the context value in a special register
8108	which is normally callee-preserved.
8109
8110	A ``swift_context`` parameter must either be the last parameter or must be
8111	followed by a ``swift_error_result`` parameter (which itself must always be
8112	the last parameter).
8113
8114	A context parameter must have pointer or reference type.)reST";
8115
8116	static const char AttrDoc_SwiftError[] = R"reST(The ``swift_error`` attribute controls whether a particular function (or
8117	Objective-C method) is imported into Swift as a throwing function, and if so,
8118	which dynamic convention it uses.
8119
8120	All of these conventions except ``none`` require the function to have an error
8121	parameter. Currently, the error parameter is always the last parameter of type
8122	``NSError*`` or ``CFErrorRef``. Swift will remove the error parameter from
8123	the imported API. When calling the API, Swift will always pass a valid address
8124	initialized to a null pointer.
8125
8126	* ``swift_error(none)`` means that the function should not be imported as
8127	throwing. The error parameter and result type will be imported normally.
8128
8129	* ``swift_error(null_result)`` means that calls to the function should be
8130	considered to have thrown if they return a null value. The return type must be
8131	a pointer type, and it will be imported into Swift with a non-optional type.
8132	This is the default error convention for Objective-C methods that return
8133	pointers.
8134
8135	* ``swift_error(zero_result)`` means that calls to the function should be
8136	considered to have thrown if they return a zero result. The return type must be
8137	an integral type. If the return type would have been imported as ``Bool``, it
8138	is instead imported as ``Void``. This is the default error convention for
8139	Objective-C methods that return a type that would be imported as ``Bool``.
8140
8141	* ``swift_error(nonzero_result)`` means that calls to the function should be
8142	considered to have thrown if they return a non-zero result. The return type must
8143	be an integral type. If the return type would have been imported as ``Bool``,
8144	it is instead imported as ``Void``.
8145
8146	* ``swift_error(nonnull_error)`` means that calls to the function should be
8147	considered to have thrown if they leave a non-null error in the error parameter.
8148	The return type is left unmodified.)reST";
8149
8150	static const char AttrDoc_SwiftErrorResult[] = R"reST(The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
8151	function as having the special error-result ABI treatment.
8152
8153	This treatment generally passes the underlying error value in and out of
8154	the function through a special register which is normally callee-preserved.
8155	This is modeled in C by pretending that the register is addressable memory:
8156
8157	- The caller appears to pass the address of a variable of pointer type.
8158	The current value of this variable is copied into the register before
8159	the call; if the call returns normally, the value is copied back into the
8160	variable.
8161
8162	- The callee appears to receive the address of a variable. This address
8163	is actually a hidden location in its own stack, initialized with the
8164	value of the register upon entry. When the function returns normally,
8165	the value in that hidden location is written back to the register.
8166
8167	A ``swift_error_result`` parameter must be the last parameter, and it must be
8168	preceded by a ``swift_context`` parameter.
8169
8170	A ``swift_error_result`` parameter must have type ``T*`` or ``T&`` for some
8171	type T. Note that no qualifiers are permitted on the intermediate level.
8172
8173	It is undefined behavior if the caller does not pass a pointer or
8174	reference to a valid object.
8175
8176	The standard convention is that the error value itself (that is, the
8177	value stored in the apparent argument) will be null upon function entry,
8178	but this is not enforced by the ABI.)reST";
8179
8180	static const char AttrDoc_SwiftImportAsNonGeneric[] = R"reST()reST";
8181
8182	static const char AttrDoc_SwiftImportPropertyAsAccessors[] = R"reST()reST";
8183
8184	static const char AttrDoc_SwiftIndirectResult[] = R"reST(The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
8185	or ``swiftasynccall`` function as having the special indirect-result ABI
8186	treatment.
8187
8188	This treatment gives the parameter the target's normal indirect-result
8189	ABI treatment, which may involve passing it differently from an ordinary
8190	parameter. However, only the first indirect result will receive this
8191	treatment. Furthermore, low-level lowering may decide that a direct result
8192	must be returned indirectly; if so, this will take priority over the
8193	``swift_indirect_result`` parameters.
8194
8195	A ``swift_indirect_result`` parameter must either be the first parameter or
8196	follow another ``swift_indirect_result`` parameter.
8197
8198	A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
8199	some object type ``T``. If ``T`` is a complete type at the point of
8200	definition of a function, it is undefined behavior if the argument
8201	value does not point to storage of adequate size and alignment for a
8202	value of type ``T``.
8203
8204	Making indirect results explicit in the signature allows C functions to
8205	directly construct objects into them without relying on language
8206	optimizations like C++'s named return value optimization (NRVO).)reST";
8207
8208	static const char AttrDoc_SwiftName[] = R"reST(The ``swift_name`` attribute provides the name of the declaration in Swift. If
8209	this attribute is absent, the name is transformed according to the algorithm
8210	built into the Swift compiler.
8211
8212	The argument is a string literal that contains the Swift name of the function,
8213	variable, or type. When renaming a function, the name may be a compound Swift
8214	name. For a type, enum constant, property, or variable declaration, the name
8215	must be a simple or qualified identifier.
8216
8217	.. code-block:: objc
8218
8219	@interface URL
8220	- (void) initWithString:(NSString *)s __attribute__((__swift_name__("URL.init(_:)")))
8221	@end
8222
8223	void __attribute__((__swift_name__("squareRoot()"))) sqrt(double v) {
8224	})reST";
8225
8226	static const char AttrDoc_SwiftNewType[] = R"reST(The ``swift_newtype`` attribute indicates that the typedef to which the
8227	attribute appertains is imported as a new Swift type of the typedef's name.
8228	Previously, the attribute was spelt ``swift_wrapper``. While the behaviour of
8229	the attribute is identical with either spelling, ``swift_wrapper`` is
8230	deprecated, only exists for compatibility purposes, and should not be used in
8231	new code.
8232
8233	* ``swift_newtype(struct)`` means that a Swift struct will be created for this
8234	typedef.
8235
8236	* ``swift_newtype(enum)`` means that a Swift enum will be created for this
8237	typedef.
8238
8239	.. code-block:: c
8240
8241	// Import UIFontTextStyle as an enum type, with enumerated values being
8242	// constants.
8243	typedef NSString * UIFontTextStyle __attribute__((__swift_newtype__(enum)));
8244
8245	// Import UIFontDescriptorFeatureKey as a structure type, with enumerated
8246	// values being members of the type structure.
8247	typedef NSString * UIFontDescriptorFeatureKey __attribute__((__swift_newtype__(struct)));)reST";
8248
8249	static const char AttrDoc_SwiftNullability[] = R"reST()reST";
8250
8251	static const char AttrDoc_SwiftObjCMembers[] = R"reST(This attribute indicates that Swift subclasses and members of Swift extensions
8252	of this class will be implicitly marked with the ``@objcMembers`` Swift
8253	attribute, exposing them back to Objective-C.)reST";
8254
8255	static const char AttrDoc_SwiftPrivate[] = R"reST(Declarations marked with the ``swift_private`` attribute are hidden from the
8256	framework client but are still made available for use within the framework or
8257	Swift SDK overlay.
8258
8259	The purpose of this attribute is to permit a more idomatic implementation of
8260	declarations in Swift while hiding the non-idiomatic one.)reST";
8261
8262	static const char AttrDoc_SwiftType[] = R"reST()reST";
8263
8264	static const char AttrDoc_SwiftVersionedAddition[] = R"reST()reST";
8265
8266	static const char AttrDoc_SwiftVersionedRemoval[] = R"reST()reST";
8267
8268	static const char AttrDoc_SysVABI[] = R"reST(On Windows x86_64 targets, this attribute changes the calling convention of a
8269	function to match the default convention used on Sys V targets such as Linux,
8270	Mac, and BSD. This attribute has no effect on other targets.)reST";
8271
8272	static const char AttrDoc_TLSModel[] = R"reST(The ``tls_model`` attribute allows you to specify which thread-local storage
8273	model to use. It accepts the following strings:
8274
8275	* global-dynamic
8276	* local-dynamic
8277	* initial-exec
8278	* local-exec
8279
8280	TLS models are mutually exclusive.)reST";
8281
8282	static const char AttrDoc_Target[] = R"reST(Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute.
8283	This attribute may be attached to a function definition and instructs
8284	the backend to use different code generation options than were passed on the
8285	command line.
8286
8287	The current set of options correspond to the existing "subtarget features" for
8288	the target with or without a "-mno-" in front corresponding to the absence
8289	of the feature, as well as ``arch="CPU"`` which will change the default "CPU"
8290	for the function.
8291
8292	For X86, the attribute also allows ``tune="CPU"`` to optimize the generated
8293	code for the given CPU without changing the available instructions.
8294
8295	For AArch64, ``arch="Arch"`` will set the architecture, similar to the -march
8296	command line options. ``cpu="CPU"`` can be used to select a specific cpu,
8297	as per the ``-mcpu`` option, similarly for ``tune=``. The attribute also allows the
8298	"branch-protection=<args>" option, where the permissible arguments and their
8299	effect on code generation are the same as for the command-line option
8300	``-mbranch-protection``.
8301
8302	Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
8303	"avx", "xop" and largely correspond to the machine specific options handled by
8304	the front end.
8305
8306	Note that this attribute does not apply transitively to nested functions such
8307	as blocks or C++ lambdas.
8308
8309	Additionally, this attribute supports function multiversioning for ELF based
8310	x86/x86-64 targets, which can be used to create multiple implementations of the
8311	same function that will be resolved at runtime based on the priority of their
8312	``target`` attribute strings. A function is considered a multiversioned function
8313	if either two declarations of the function have different ``target`` attribute
8314	strings, or if it has a ``target`` attribute string of ``default``. For
8315	example:
8316
8317	.. code-block:: c++
8318
8319	__attribute__((target("arch=atom")))
8320	void foo() {} // will be called on 'atom' processors.
8321	__attribute__((target("default")))
8322	void foo() {} // will be called on any other processors.
8323
8324	All multiversioned functions must contain a ``default`` (fallback)
8325	implementation, otherwise usages of the function are considered invalid.
8326	Additionally, a function may not become multiversioned after its first use.)reST";
8327
8328	static const char AttrDoc_TargetClones[] = R"reST(Clang supports the ``target_clones("OPTIONS")`` attribute. This attribute may be
8329	attached to a function declaration and causes function multiversioning, where
8330	multiple versions of the function will be emitted with different code
8331	generation options. Additionally, these versions will be resolved at runtime
8332	based on the priority of their attribute options. All ``target_clone`` functions
8333	are considered multiversioned functions.
8334
8335	For AArch64 target:
8336	The attribute contains comma-separated strings of target features joined by "+"
8337	sign. For example:
8338
8339	.. code-block:: c++
8340
8341	__attribute__((target_clones("sha2+memtag", "fcma+sve2-pmull128")))
8342	void foo() {}
8343
8344	For every multiversioned function a ``default`` (fallback) implementation
8345	always generated if not specified directly.
8346
8347	For x86/x86-64 targets:
8348	All multiversioned functions must contain a ``default`` (fallback)
8349	implementation, otherwise usages of the function are considered invalid.
8350	Additionally, a function may not become multiversioned after its first use.
8351
8352	The options to ``target_clones`` can either be a target-specific architecture
8353	(specified as ``arch=CPU``), or one of a list of subtarget features.
8354
8355	Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
8356	"avx", "xop" and largely correspond to the machine specific options handled by
8357	the front end.
8358
8359	The versions can either be listed as a comma-separated sequence of string
8360	literals or as a single string literal containing a comma-separated list of
8361	versions. For compatibility with GCC, the two formats can be mixed. For
8362	example, the following will emit 4 versions of the function:
8363
8364	.. code-block:: c++
8365
8366	__attribute__((target_clones("arch=atom,avx2","arch=ivybridge","default")))
8367	void foo() {}
8368
8369	For targets that support the GNU indirect function (IFUNC) feature, dispatch
8370	is performed by emitting an indirect function that is resolved to the appropriate
8371	target clone at load time. The indirect function is given the name the
8372	multiversioned function would have if it had been declared without the attribute.
8373	For backward compatibility with earlier Clang releases, a function alias with an
8374	``.ifunc`` suffix is also emitted. The ``.ifunc`` suffixed symbol is a deprecated
8375	feature and support for it may be removed in the future.)reST";
8376
8377	static const char AttrDoc_TargetVersion[] = R"reST(For AArch64 target clang supports function multiversioning by
8378	``__attribute__((target_version("OPTIONS")))`` attribute. When applied to a
8379	function it instructs compiler to emit multiple function versions based on
8380	``target_version`` attribute strings, which resolved at runtime depend on their
8381	priority and target features availability. One of the versions is always
8382	( implicitly or explicitly ) the ``default`` (fallback). Attribute strings can
8383	contain dependent features names joined by the "+" sign.
8384
8385	For targets that support the GNU indirect function (IFUNC) feature, dispatch
8386	is performed by emitting an indirect function that is resolved to the appropriate
8387	target clone at load time. The indirect function is given the name the
8388	multiversioned function would have if it had been declared without the attribute.
8389	For backward compatibility with earlier Clang releases, a function alias with an
8390	``.ifunc`` suffix is also emitted. The ``.ifunc`` suffixed symbol is a deprecated
8391	feature and support for it may be removed in the future.)reST";
8392
8393	static const char AttrDoc_TestTypestate[] = R"reST(Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
8394	returns true if the object is in the specified state..)reST";
8395
8396	static const char AttrDoc_ThisCall[] = R"reST(On 32-bit x86 targets, this attribute changes the calling convention of a
8397	function to use ECX for the first parameter (typically the implicit ``this``
8398	parameter of C++ methods) and clear parameters off of the stack on return. This
8399	convention does not support variadic calls or unprototyped functions in C, and
8400	has no effect on x86_64 targets. See the documentation for `__thiscall`_ on
8401	MSDN.
8402
8403	.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx)reST";
8404
8405	static const char AttrDoc_Thread[] = R"reST(The ``__declspec(thread)`` attribute declares a variable with thread local
8406	storage. It is available under the ``-fms-extensions`` flag for MSVC
8407	compatibility. See the documentation for `__declspec(thread)`_ on MSDN.
8408
8409	.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
8410
8411	In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
8412	GNU ``__thread`` keyword. The variable must not have a destructor and must have
8413	a constant initializer, if any. The attribute only applies to variables
8414	declared with static storage duration, such as globals, class static data
8415	members, and static locals.)reST";
8416
8417	static const char AttrDoc_TransparentUnion[] = R"reST(This attribute can be applied to a union to change the behavior of calls to
8418	functions that have an argument with a transparent union type. The compiler
8419	behavior is changed in the following manner:
8420
8421	- A value whose type is any member of the transparent union can be passed as an
8422	argument without the need to cast that value.
8423
8424	- The argument is passed to the function using the calling convention of the
8425	first member of the transparent union. Consequently, all the members of the
8426	transparent union should have the same calling convention as its first member.
8427
8428	Transparent unions are not supported in C++.)reST";
8429
8430	static const char AttrDoc_TrivialABI[] = R"reST(The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
8431	It instructs the compiler to pass and return the type using the C ABI for the
8432	underlying type when the type would otherwise be considered non-trivial for the
8433	purpose of calls.
8434	A class annotated with ``trivial_abi`` can have non-trivial destructors or
8435	copy/move constructors without automatically becoming non-trivial for the
8436	purposes of calls. For example:
8437
8438	.. code-block:: c++
8439
8440	// A is trivial for the purposes of calls because ``trivial_abi`` makes the
8441	// user-provided special functions trivial.
8442	struct __attribute__((trivial_abi)) A {
8443	~A();
8444	A(const A &);
8445	A(A &&);
8446	int x;
8447	};
8448
8449	// B's destructor and copy/move constructor are considered trivial for the
8450	// purpose of calls because A is trivial.
8451	struct B {
8452	A a;
8453	};
8454
8455	If a type is trivial for the purposes of calls, has a non-trivial destructor,
8456	and is passed as an argument by value, the convention is that the callee will
8457	destroy the object before returning. The lifetime of the copy of the parameter
8458	in the caller ends without a destructor call when the call begins.
8459
8460	If a type is trivial for the purpose of calls, it is assumed to be trivially
8461	relocatable for the purpose of ``__is_trivially_relocatable`` and
8462	``__builtin_is_cpp_trivially_relocatable``.
8463	When a type marked with ``[[trivial_abi]]`` is used as a function argument,
8464	the compiler may omit the call to the copy constructor.
8465	Thus, side effects of the copy constructor are potentially not performed.
8466	For example, objects that contain pointers to themselves or otherwise depend
8467	on their address (or the address or their subobjects) should not be declared
8468	``[[trivial_abi]]``.
8469
8470	Attribute ``trivial_abi`` has no effect in the following cases:
8471
8472	- The class directly declares a virtual base or virtual methods.
8473	- Copy constructors and move constructors of the class are all deleted.
8474	- The class has a base class that is non-trivial for the purposes of calls.
8475	- The class has a non-static data member whose type is non-trivial for the
8476	purposes of calls, which includes:
8477
8478	- classes that are non-trivial for the purposes of calls
8479	- __weak-qualified types in Objective-C++
8480	- arrays of any of the above)reST";
8481
8482	static const char AttrDoc_TryAcquireCapability[] = R"reST(Marks a function that attempts to acquire a capability. This function may fail to
8483	actually acquire the capability; they accept a Boolean value determining
8484	whether acquiring the capability means success (true), or failing to acquire
8485	the capability means success (false).)reST";
8486
8487	static const char AttrDoc_TypeNonNull[] = R"reST(The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful
8488	value for a value of the ``_Nonnull`` pointer type. For example, given a
8489	declaration such as:
8490
8491	.. code-block:: c
8492
8493	int fetch(int * _Nonnull ptr);
8494
8495	a caller of ``fetch`` should not provide a null value, and the compiler will
8496	produce a warning if it sees a literal null value passed to ``fetch``. Note
8497	that, unlike the declaration attribute ``nonnull``, the presence of
8498	``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch``
8499	is free to consider null undefined behavior or (perhaps for
8500	backward-compatibility reasons) defensively handle null.)reST";
8501
8502	static const char AttrDoc_TypeNullUnspecified[] = R"reST(The ``_Null_unspecified`` nullability qualifier indicates that neither the
8503	``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer
8504	type. It is used primarily to indicate that the role of null with specific
8505	pointers in a nullability-annotated header is unclear, e.g., due to
8506	overly-complex implementations or historical factors with a long-lived API.)reST";
8507
8508	static const char AttrDoc_TypeNullable[] = R"reST(The ``_Nullable`` nullability qualifier indicates that a value of the
8509	``_Nullable`` pointer type can be null. For example, given:
8510
8511	.. code-block:: c
8512
8513	int fetch_or_zero(int * _Nullable ptr);
8514
8515	a caller of ``fetch_or_zero`` can provide null.
8516
8517	The ``_Nullable`` attribute on classes indicates that the given class can
8518	represent null values, and so the ``_Nullable``, ``_Nonnull`` etc qualifiers
8519	make sense for this type. For example:
8520
8521	.. code-block:: c
8522
8523	class _Nullable ArenaPointer { ... };
8524
8525	ArenaPointer _Nonnull x = ...;
8526	ArenaPointer _Nullable y = nullptr;)reST";
8527
8528	static const char AttrDoc_TypeNullableResult[] = R"reST(The ``_Nullable_result`` nullability qualifier means that a value of the
8529	``_Nullable_result`` pointer can be ``nil``, just like ``_Nullable``. Where this
8530	attribute differs from ``_Nullable`` is when it's used on a parameter to a
8531	completion handler in a Swift async method. For instance, here:
8532
8533	.. code-block:: objc
8534
8535	-(void)fetchSomeDataWithID:(int)identifier
8536	completionHandler:(void (^)(Data _Nullable_result result, NSError error))completionHandler;
8537
8538	This method asynchronously calls ``completionHandler`` when the data is
8539	available, or calls it with an error. ``_Nullable_result`` indicates to the
8540	Swift importer that this is the uncommon case where ``result`` can get ``nil``
8541	even if no error has occurred, and will therefore import it as a Swift optional
8542	type. Otherwise, if ``result`` was annotated with ``_Nullable``, the Swift
8543	importer will assume that ``result`` will always be non-nil unless an error
8544	occurred.)reST";
8545
8546	static const char AttrDoc_TypeTagForDatatype[] = R"reST(When declaring a variable, use
8547	``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
8548	is tied to the ``type`` argument given to the attribute.
8549
8550	In the attribute prototype above:
8551	* ``kind`` is an identifier that should be used when annotating all applicable
8552	type tags.
8553	* ``type`` indicates the name of the type.
8554
8555	Clang supports annotating type tags of two forms.
8556
8557	* Type tag that is a reference to a declared identifier.
8558	Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
8559	identifier:
8560
8561	.. code-block:: c++
8562
8563	typedef int MPI_Datatype;
8564	extern struct mpi_datatype mpi_datatype_int
8565	__attribute__(( type_tag_for_datatype(mpi,int) ));
8566	#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
8567	// &mpi_datatype_int is a type tag. It is tied to type "int".
8568
8569	* Type tag that is an integral literal.
8570	Declare a ``static const`` variable with an initializer value and attach
8571	``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
8572
8573	.. code-block:: c++
8574
8575	typedef int MPI_Datatype;
8576	static const MPI_Datatype mpi_datatype_int
8577	__attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
8578	#define MPI_INT ((MPI_Datatype) 42)
8579	// The number 42 is a type tag. It is tied to type "int".
8580
8581
8582	The ``type_tag_for_datatype`` attribute also accepts an optional third argument
8583	that determines how the type of the function argument specified by either
8584	``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
8585	tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
8586	function argument specified by ``arg_idx`` is compared against the type
8587	associated with the type tag. Also recall that for the ``pointer_with_type_tag``
8588	attribute, the pointee type of the function argument specified by ``ptr_idx`` is
8589	compared against the type associated with the type tag.) There are two supported
8590	values for this optional third argument:
8591
8592	* ``layout_compatible`` will cause types to be compared according to
8593	layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
8594	layout-compatibility rules for two standard-layout struct types and for two
8595	standard-layout union types). This is useful when creating a type tag
8596	associated with a struct or union type. For example:
8597
8598	.. code-block:: c++
8599
8600	/* In mpi.h */
8601	typedef int MPI_Datatype;
8602	struct internal_mpi_double_int { double d; int i; };
8603	extern struct mpi_datatype mpi_datatype_double_int
8604	__attribute__(( type_tag_for_datatype(mpi,
8605	struct internal_mpi_double_int, layout_compatible) ));
8606
8607	#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
8608
8609	int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
8610	__attribute__(( pointer_with_type_tag(mpi,1,3) ));
8611
8612	/* In user code */
8613	struct my_pair { double a; int b; };
8614	struct my_pair *buffer;
8615	MPI_Send(buffer, 1, MPI_DOUBLE_INT /, ... /); // no warning because the
8616	// layout of my_pair is
8617	// compatible with that of
8618	// internal_mpi_double_int
8619
8620	struct my_int_pair { int a; int b; }
8621	struct my_int_pair *buffer2;
8622	MPI_Send(buffer2, 1, MPI_DOUBLE_INT /, ... /); // warning because the
8623	// layout of my_int_pair
8624	// does not match that of
8625	// internal_mpi_double_int
8626
8627	* ``must_be_null`` specifies that the function argument specified by either
8628	``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
8629	the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
8630	The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
8631	example:
8632
8633	.. code-block:: c++
8634
8635	/* In mpi.h */
8636	typedef int MPI_Datatype;
8637	extern struct mpi_datatype mpi_datatype_null
8638	__attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
8639
8640	#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
8641	int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
8642	__attribute__(( pointer_with_type_tag(mpi,1,3) ));
8643
8644	/* In user code */
8645	struct my_pair { double a; int b; };
8646	struct my_pair *buffer;
8647	MPI_Send(buffer, 1, MPI_DATATYPE_NULL /, ... /); // warning: MPI_DATATYPE_NULL
8648	// was specified but buffer
8649	// is not a null pointer)reST";
8650
8651	static const char AttrDoc_TypeVisibility[] = R"reST(The ``type_visibility`` attribute allows the visibility of a type and its vague
8652	linkage objects (vtable, typeinfo, typeinfo name) to be controlled separately from
8653	the visibility of functions and data members of the type.
8654
8655	For example, this can be used to give default visibility to the typeinfo and the vtable
8656	of a type while still keeping hidden visibility on its member functions and static data
8657	members.
8658
8659	This attribute can only be applied to types and namespaces.
8660
8661	If both ``visibility`` and ``type_visibility`` are applied to a type or a namespace, the
8662	visibility specified with the ``type_visibility`` attribute overrides the visibility
8663	provided with the regular ``visibility`` attribute.)reST";
8664
8665	static const char AttrDoc_UPtr[] = R"reST(The ``__uptr`` qualifier specifies that a 32-bit pointer should be zero
8666	extended when converted to a 64-bit pointer.)reST";
8667
8668	static const char AttrDoc_Unavailable[] = R"reST(No documentation.)reST";
8669
8670	static const char AttrDoc_Uninitialized[] = R"reST(The command-line parameter ``-ftrivial-auto-var-init=*`` can be used to
8671	initialize trivial automatic stack variables. By default, trivial automatic
8672	stack variables are uninitialized. This attribute is used to override the
8673	command-line parameter, forcing variables to remain uninitialized. It has no
8674	semantic meaning in that using uninitialized values is undefined behavior,
8675	it rather documents the programmer's intent.)reST";
8676
8677	static const char AttrDoc_Unlikely[] = R"reST(The ``likely`` and ``unlikely`` attributes are used as compiler hints.
8678	The attributes are used to aid the compiler to determine which branch is
8679	likely or unlikely to be taken. This is done by marking the branch substatement
8680	with one of the two attributes.
8681
8682	It isn't allowed to annotate a single statement with both ``likely`` and
8683	``unlikely``. Annotating the ``true`` and ``false`` branch of an ``if``
8684	statement with the same likelihood attribute will result in a diagnostic and
8685	the attributes are ignored on both branches.
8686
8687	In a ``switch`` statement it's allowed to annotate multiple ``case`` labels
8688	or the ``default`` label with the same likelihood attribute. This makes
8689	* all labels without an attribute have a neutral likelihood,
8690	* all labels marked ``[[likely]]`` have an equally positive likelihood, and
8691	* all labels marked ``[[unlikely]]`` have an equally negative likelihood.
8692	The neutral likelihood is the more likely of path execution than the negative
8693	likelihood. The positive likelihood is the more likely of path of execution
8694	than the neutral likelihood.
8695
8696	These attributes have no effect on the generated code when using
8697	PGO (Profile-Guided Optimization) or at optimization level 0.
8698
8699	In Clang, the attributes will be ignored if they're not placed on
8700	* the ``case`` or ``default`` label of a ``switch`` statement,
8701	* or on the substatement of an ``if`` or ``else`` statement,
8702	* or on the substatement of an ``for`` or ``while`` statement.
8703	The C++ Standard recommends to honor them on every statement in the
8704	path of execution, but that can be confusing:
8705
8706	.. code-block:: c++
8707
8708	if (b) {
8709	[[unlikely]] --b; // In the path of execution,
8710	// this branch is considered unlikely.
8711	}
8712
8713	if (b) {
8714	--b;
8715	if(b)
8716	return;
8717	[[unlikely]] --b; // Not in the path of execution,
8718	} // the branch has no likelihood information.
8719
8720	if (b) {
8721	--b;
8722	foo(b);
8723	// Whether or not the next statement is in the path of execution depends
8724	// on the declaration of foo():
8725	// In the path of execution: void foo(int);
8726	// Not in the path of execution: [[noreturn]] void foo(int);
8727	// This means the likelihood of the branch depends on the declaration
8728	// of foo().
8729	[[unlikely]] --b;
8730	}
8731
8732
8733	Below are some example usages of the likelihood attributes and their effects:
8734
8735	.. code-block:: c++
8736
8737	if (b) [[likely]] { // Placement on the first statement in the branch.
8738	// The compiler will optimize to execute the code here.
8739	} else {
8740	}
8741
8742	if (b)
8743	[[unlikely]] b++; // Placement on the first statement in the branch.
8744	else {
8745	// The compiler will optimize to execute the code here.
8746	}
8747
8748	if (b) {
8749	[[unlikely]] b++; // Placement on the second statement in the branch.
8750	} // The attribute will be ignored.
8751
8752	if (b) [[likely]] {
8753	[[unlikely]] b++; // No contradiction since the second attribute
8754	} // is ignored.
8755
8756	if (b)
8757	;
8758	else [[likely]] {
8759	// The compiler will optimize to execute the code here.
8760	}
8761
8762	if (b)
8763	;
8764	else
8765	// The compiler will optimize to execute the next statement.
8766	[[likely]] b = f();
8767
8768	if (b) [[likely]]; // Both branches are likely. A diagnostic is issued
8769	else [[likely]]; // and the attributes are ignored.
8770
8771	if (b)
8772	[[likely]] int i = 5; // Issues a diagnostic since the attribute
8773	// isn't allowed on a declaration.
8774
8775	switch (i) {
8776	[[likely]] case 1: // This value is likely
8777	...
8778	break;
8779
8780	[[unlikely]] case 2: // This value is unlikely
8781	...
8782	[[fallthrough]];
8783
8784	case 3: // No likelihood attribute
8785	...
8786	[[likely]] break; // No effect
8787
8788	case 4: [[likely]] { // attribute on substatement has no effect
8789	...
8790	break;
8791	}
8792
8793	[[unlikely]] default: // All other values are unlikely
8794	...
8795	break;
8796	}
8797
8798	switch (i) {
8799	[[likely]] case 0: // This value and code path is likely
8800	...
8801	[[fallthrough]];
8802
8803	case 1: // No likelihood attribute, code path is neutral
8804	break; // falling through has no effect on the likelihood
8805
8806	case 2: // No likelihood attribute, code path is neutral
8807	[[fallthrough]];
8808
8809	[[unlikely]] default: // This value and code path are both unlikely
8810	break;
8811	}
8812
8813	for(int i = 0; i != size; ++i) [[likely]] {
8814	... // The loop is the likely path of execution
8815	}
8816
8817	for(const auto &E : Elements) [[likely]] {
8818	... // The loop is the likely path of execution
8819	}
8820
8821	while(i != size) [[unlikely]] {
8822	... // The loop is the unlikely path of execution
8823	} // The generated code will optimize to skip the loop body
8824
8825	while(true) [[unlikely]] {
8826	... // The attribute has no effect
8827	} // Clang elides the comparison and generates an infinite
8828	// loop)reST";
8829
8830	static const char AttrDoc_UnsafeBufferUsage[] = R"reST(The attribute ``[[clang::unsafe_buffer_usage]]`` should be placed on functions
8831	that need to be avoided as they are prone to buffer overflows or unsafe buffer
8832	struct fields. It is designed to work together with the off-by-default compiler
8833	warning ``-Wunsafe-buffer-usage`` to help codebases transition away from raw pointer
8834	based buffer management, in favor of safer abstractions such as C++20 ``std::span``.
8835	The attribute causes ``-Wunsafe-buffer-usage`` to warn on every use of the function or
8836	the field it is attached to, and it may also lead to emission of automatic fix-it
8837	hints which would help the user replace the use of unsafe functions(/fields) with safe
8838	alternatives, though the attribute can be used even when the fix can't be automated.
8839
8840	* Attribute attached to functions: The attribute suppresses all
8841	``-Wunsafe-buffer-usage`` warnings within the function it is attached to, as the
8842	function is now classified as unsafe. The attribute should be used carefully, as it
8843	will silence all unsafe operation warnings inside the function; including any new
8844	unsafe operations introduced in the future.
8845
8846	The attribute is warranted even if the only way a function can overflow
8847	the buffer is by violating the function's preconditions. For example, it
8848	would make sense to put the attribute on function ``foo()`` below because
8849	passing an incorrect size parameter would cause a buffer overflow:
8850
8851	.. code-block:: c++
8852
8853	[[clang::unsafe_buffer_usage]]
8854	void foo(int *buf, size_t size) {
8855	for (size_t i = 0; i < size; ++i) {
8856	buf[i] = i;
8857	}
8858	}
8859
8860	The attribute is NOT warranted when the function uses safe abstractions,
8861	assuming that these abstractions weren't misused outside the function.
8862	For example, function ``bar()`` below doesn't need the attribute,
8863	because assuming that the container ``buf`` is well-formed (has size that
8864	fits the original buffer it refers to), overflow cannot occur:
8865
8866	.. code-block:: c++
8867
8868	void bar(std::span<int> buf) {
8869	for (size_t i = 0; i < buf.size(); ++i) {
8870	buf[i] = i;
8871	}
8872	}
8873
8874	In this case function ``bar()`` enables the user to keep the buffer
8875	"containerized" in a span for as long as possible. On the other hand,
8876	Function ``foo()`` in the previous example may have internal
8877	consistency, but by accepting a raw buffer it requires the user to unwrap
8878	their span, which is undesirable according to the programming model
8879	behind ``-Wunsafe-buffer-usage``.
8880
8881	The attribute is warranted when a function accepts a raw buffer only to
8882	immediately put it into a span:
8883
8884	.. code-block:: c++
8885
8886	[[clang::unsafe_buffer_usage]]
8887	void baz(int *buf, size_t size) {
8888	std::span<int> sp{ buf, size };
8889	for (size_t i = 0; i < sp.size(); ++i) {
8890	sp[i] = i;
8891	}
8892	}
8893
8894	In this case ``baz()`` does not contain any unsafe operations, but the awkward
8895	parameter type causes the caller to unwrap the span unnecessarily.
8896	Note that regardless of the attribute, code inside ``baz()`` isn't flagged
8897	by ``-Wunsafe-buffer-usage`` as unsafe. It is definitely undesirable,
8898	but if ``baz()`` is on an API surface, there is no way to improve it
8899	to make it as safe as ``bar()`` without breaking the source and binary
8900	compatibility with existing users of the function. In such cases
8901	the proper solution would be to create a different function (possibly
8902	an overload of ``baz()``) that accepts a safe container like ``bar()``,
8903	and then use the attribute on the original ``baz()`` to help the users
8904	update their code to use the new function.
8905
8906	* Attribute attached to fields: The attribute should only be attached to
8907	struct fields, if the fields can not be updated to a safe type with bounds
8908	check, such as std::span. In other words, the buffers prone to unsafe accesses
8909	should always be updated to use safe containers/views and attaching the attribute
8910	must be last resort when such an update is infeasible.
8911
8912	The attribute can be placed on individual fields or a set of them as shown below.
8913
8914	.. code-block:: c++
8915
8916	struct A {
8917	[[clang::unsafe_buffer_usage]]
8918	int *ptr1;
8919
8920	[[clang::unsafe_buffer_usage]]
8921	int *ptr2, buf[10];
8922
8923	[[clang::unsafe_buffer_usage]]
8924	size_t sz;
8925	};
8926
8927	Here, every read/write to the fields ptr1, ptr2, buf and sz will trigger a warning
8928	that the field has been explcitly marked as unsafe due to unsafe-buffer operations.)reST";
8929
8930	static const char AttrDoc_Unused[] = R"reST(When passing the ``-Wunused`` flag to Clang, entities that are unused by the
8931	program may be diagnosed. The ``[[maybe_unused]]`` (or
8932	``__attribute__((unused))``) attribute can be used to silence such diagnostics
8933	when the entity cannot be removed. For instance, a local variable may exist
8934	solely for use in an ``assert()`` statement, which makes the local variable
8935	unused when ``NDEBUG`` is defined.
8936
8937	The attribute may be applied to the declaration of a class, a typedef, a
8938	variable, a function or method, a function parameter, an enumeration, an
8939	enumerator, a non-static data member, or a label.
8940
8941	.. code-block:: c++
8942
8943	#include <cassert>
8944
8945	[[maybe_unused]] void f([[maybe_unused]] bool thing1,
8946	[[maybe_unused]] bool thing2) {
8947	[[maybe_unused]] bool b = thing1 && thing2;
8948	assert(b);
8949	})reST";
8950
8951	static const char AttrDoc_UseHandle[] = R"reST(A function taking a handle by value might close the handle. If a function
8952	parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
8953	the state of the handle. It is also assumed to require an open handle to work with.
8954	The attribute requires a string literal argument to identify the handle being used.
8955
8956	.. code-block:: c++
8957
8958	zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
8959	zx_time_t deadline,
8960	zx_port_packet_t* packet);)reST";
8961
8962	static const char AttrDoc_Used[] = R"reST(This attribute, when attached to a function or variable definition, indicates
8963	that there may be references to the entity which are not apparent in the source
8964	code. For example, it may be referenced from inline ``asm``, or it may be
8965	found through a dynamic symbol or section lookup.
8966
8967	The compiler must emit the definition even if it appears to be unused, and it
8968	must not apply optimizations which depend on fully understanding how the entity
8969	is used.
8970
8971	Whether this attribute has any effect on the linker depends on the target and
8972	the linker. Most linkers support the feature of section garbage collection
8973	(``--gc-sections``), also known as "dead stripping" (``ld64 -dead_strip``) or
8974	discarding unreferenced sections (``link.exe /OPT:REF``). On COFF and Mach-O
8975	targets (Windows and Apple platforms), the `used` attribute prevents symbols
8976	from being removed by linker section GC. On ELF targets, it has no effect on its
8977	own, and the linker may remove the definition if it is not otherwise referenced.
8978	This linker GC can be avoided by also adding the ``retain`` attribute. Note
8979	that ``retain`` requires special support from the linker; see that attribute's
8980	documentation for further information.)reST";
8981
8982	static const char AttrDoc_UsingIfExists[] = R"reST(The ``using_if_exists`` attribute applies to a using-declaration. It allows
8983	programmers to import a declaration that potentially does not exist, instead
8984	deferring any errors to the point of use. For instance:
8985
8986	.. code-block:: c++
8987
8988	namespace empty_namespace {};
8989	__attribute__((using_if_exists))
8990	using empty_namespace::does_not_exist; // no error!
8991
8992	does_not_exist x; // error: use of unresolved 'using_if_exists'
8993
8994	The C++ spelling of the attribute (`[[clang::using_if_exists]]`) is also
8995	supported as a clang extension, since ISO C++ doesn't support attributes in this
8996	position. If the entity referred to by the using-declaration is found by name
8997	lookup, the attribute has no effect. This attribute is useful for libraries
8998	(primarily, libc++) that wish to redeclare a set of declarations in another
8999	namespace, when the availability of those declarations is difficult or
9000	impossible to detect at compile time with the preprocessor.)reST";
9001
9002	static const char AttrDoc_Uuid[] = R"reST(No documentation.)reST";
9003
9004	static const char AttrDoc_VTablePointerAuthentication[] = R"reST(No documentation.)reST";
9005
9006	static const char AttrDoc_VecReturn[] = R"reST(No documentation.)reST";
9007
9008	static const char AttrDoc_VecTypeHint[] = R"reST(No documentation.)reST";
9009
9010	static const char AttrDoc_VectorCall[] = R"reST(On 32-bit x86 and x86_64 targets, this attribute changes the calling
9011	convention of a function to pass vector parameters in SSE registers.
9012
9013	On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
9014	The first two integer parameters are passed in ECX and EDX. Subsequent integer
9015	parameters are passed in memory, and callee clears the stack. On x86_64
9016	targets, the callee does not clear the stack, and integer parameters are
9017	passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
9018	convention.
9019
9020	On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
9021	passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
9022	passed in sequential SSE registers if enough are available. If AVX is enabled,
9023	256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
9024	cannot be passed in registers for any reason is passed by reference, which
9025	allows the caller to align the parameter memory.
9026
9027	See the documentation for `__vectorcall`_ on MSDN for more details.
9028
9029	.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx)reST";
9030
9031	static const char AttrDoc_Visibility[] = R"reST(No documentation.)reST";
9032
9033	static const char AttrDoc_WarnUnused[] = R"reST(No documentation.)reST";
9034
9035	static const char AttrDoc_WarnUnusedResult[] = R"reST(Clang supports the ability to diagnose when the results of a function call
9036	expression are discarded under suspicious circumstances. A diagnostic is
9037	generated when a function or its return type is marked with ``[[nodiscard]]``
9038	(or ``__attribute__((warn_unused_result))``) and the function call appears as a
9039	potentially-evaluated discarded-value expression that is not explicitly cast to
9040	``void``.
9041
9042	A string literal may optionally be provided to the attribute, which will be
9043	reproduced in any resulting diagnostics. Redeclarations using different forms
9044	of the attribute (with or without the string literal or with different string
9045	literal contents) are allowed. If there are redeclarations of the entity with
9046	differing string literals, it is unspecified which one will be used by Clang
9047	in any resulting diagnostics.
9048
9049	.. code-block:: c++
9050
9051	struct [[nodiscard]] error_info { /.../ };
9052	error_info enable_missile_safety_mode();
9053
9054	void launch_missiles();
9055	void test_missiles() {
9056	enable_missile_safety_mode(); // diagnoses
9057	launch_missiles();
9058	}
9059	error_info &foo();
9060	void f() { foo(); } // Does not diagnose, error_info is a reference.
9061
9062	Additionally, discarded temporaries resulting from a call to a constructor
9063	marked with ``[[nodiscard]]`` or a constructor of a type marked
9064	``[[nodiscard]]`` will also diagnose. This also applies to type conversions that
9065	use the annotated ``[[nodiscard]]`` constructor or result in an annotated type.
9066
9067	.. code-block:: c++
9068
9069	struct [[nodiscard]] marked_type {/../ };
9070	struct marked_ctor {
9071	[[nodiscard]] marked_ctor();
9072	marked_ctor(int);
9073	};
9074
9075	struct S {
9076	operator marked_type() const;
9077	[[nodiscard]] operator int() const;
9078	};
9079
9080	void usages() {
9081	marked_type(); // diagnoses.
9082	marked_ctor(); // diagnoses.
9083	marked_ctor(3); // Does not diagnose, int constructor isn't marked nodiscard.
9084
9085	S s;
9086	static_cast<marked_type>(s); // diagnoses
9087	(int)s; // diagnoses
9088	})reST";
9089
9090	static const char AttrDoc_Weak[] = R"reST(In supported output formats the ``weak`` attribute can be used to
9091	specify that a variable or function should be emitted as a symbol with
9092	``weak`` (if a definition) or ``extern_weak`` (if a declaration of an
9093	external symbol) `linkage
9094	<https://llvm.org/docs/LangRef.html#linkage-types>`_.
9095
9096	If there is a non-weak definition of the symbol the linker will select
9097	that over the weak. They must have same type and alignment (variables
9098	must also have the same size), but may have a different value.
9099
9100	If there are multiple weak definitions of same symbol, but no non-weak
9101	definition, they should have same type, size, alignment and value, the
9102	linker will select one of them (see also selectany_ attribute).
9103
9104	If the ``weak`` attribute is applied to a ``const`` qualified variable
9105	definition that variable is no longer consider a compiletime constant
9106	as its value can change during linking (or dynamic linking). This
9107	means that it can e.g no longer be part of an initializer expression.
9108
9109	.. code-block:: c
9110
9111	const int ANSWER __attribute__ ((weak)) = 42;
9112
9113	/* This function may be replaced link-time */
9114	__attribute__ ((weak)) void debug_log(const char *msg)
9115	{
9116	fprintf(stderr, "DEBUG: %s\n", msg);
9117	}
9118
9119	int main(int argc, const char **argv)
9120	{
9121	debug_log ("Starting up...");
9122
9123	/* This may print something else than "6 * 7 = 42",
9124	if there is a non-weak definition of "ANSWER" in
9125	an object linked in */
9126	printf("6 * 7 = %d\n", ANSWER);
9127
9128	return 0;
9129	}
9130
9131	If an external declaration is marked weak and that symbol does not
9132	exist during linking (possibly dynamic) the address of the symbol will
9133	evaluate to NULL.
9134
9135	.. code-block:: c
9136
9137	void may_not_exist(void) __attribute__ ((weak));
9138
9139	int main(int argc, const char **argv)
9140	{
9141	if (may_not_exist) {
9142	may_not_exist();
9143	} else {
9144	printf("Function did not exist\n");
9145	}
9146	return 0;
9147	})reST";
9148
9149	static const char AttrDoc_WeakImport[] = R"reST(No documentation.)reST";
9150
9151	static const char AttrDoc_WeakRef[] = R"reST(No documentation.)reST";
9152
9153	static const char AttrDoc_WebAssemblyExportName[] = R"reST(Clang supports the ``__attribute__((export_name(<name>)))``
9154	attribute for the WebAssembly target. This attribute may be attached to a
9155	function declaration, where it modifies how the symbol is to be exported
9156	from the linked WebAssembly.
9157
9158	WebAssembly functions are exported via string name. By default when a symbol
9159	is exported, the export name for C/C++ symbols are the same as their C/C++
9160	symbol names. This attribute can be used to override the default behavior, and
9161	request a specific string name be used instead.)reST";
9162
9163	static const char AttrDoc_WebAssemblyFuncref[] = R"reST(Clang supports the ``__attribute__((export_name(<name>)))``
9164	attribute for the WebAssembly target. This attribute may be attached to a
9165	function declaration, where it modifies how the symbol is to be exported
9166	from the linked WebAssembly.
9167
9168	WebAssembly functions are exported via string name. By default when a symbol
9169	is exported, the export name for C/C++ symbols are the same as their C/C++
9170	symbol names. This attribute can be used to override the default behavior, and
9171	request a specific string name be used instead.)reST";
9172
9173	static const char AttrDoc_WebAssemblyImportModule[] = R"reST(Clang supports the ``__attribute__((import_module(<module_name>)))``
9174	attribute for the WebAssembly target. This attribute may be attached to a
9175	function declaration, where it modifies how the symbol is to be imported
9176	within the WebAssembly linking environment.
9177
9178	WebAssembly imports use a two-level namespace scheme, consisting of a module
9179	name, which typically identifies a module from which to import, and a field
9180	name, which typically identifies a field from that module to import. By
9181	default, module names for C/C++ symbols are assigned automatically by the
9182	linker. This attribute can be used to override the default behavior, and
9183	request a specific module name be used instead.)reST";
9184
9185	static const char AttrDoc_WebAssemblyImportName[] = R"reST(Clang supports the ``__attribute__((import_name(<name>)))``
9186	attribute for the WebAssembly target. This attribute may be attached to a
9187	function declaration, where it modifies how the symbol is to be imported
9188	within the WebAssembly linking environment.
9189
9190	WebAssembly imports use a two-level namespace scheme, consisting of a module
9191	name, which typically identifies a module from which to import, and a field
9192	name, which typically identifies a field from that module to import. By
9193	default, field names for C/C++ symbols are the same as their C/C++ symbol
9194	names. This attribute can be used to override the default behavior, and
9195	request a specific field name be used instead.)reST";
9196
9197	static const char AttrDoc_WorkGroupSizeHint[] = R"reST(No documentation.)reST";
9198
9199	static const char AttrDoc_X86ForceAlignArgPointer[] = R"reST(Use this attribute to force stack alignment.
9200
9201	Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
9202	(like 'movaps') that work with the stack require operands to be 16-byte aligned.
9203	This attribute realigns the stack in the function prologue to make sure the
9204	stack can be used with SSE instructions.
9205
9206	Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
9207	Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
9208	rare cases where the caller does not align the stack properly (e.g. flow
9209	jumps from i386 arch code).
9210
9211	.. code-block:: c
9212
9213	__attribute__ ((force_align_arg_pointer))
9214	void f () {
9215	...
9216	})reST";
9217
9218	static const char AttrDoc_XRayInstrument[] = R"reST(``__attribute__((xray_always_instrument))`` or
9219	``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++),
9220	methods (in Objective C), and free functions (in C, C++, and Objective C) to be
9221	instrumented with XRay. This will cause the function to always have space at
9222	the beginning and exit points to allow for runtime patching.
9223
9224	Conversely, ``__attribute__((xray_never_instrument))`` or
9225	``[[clang::xray_never_instrument]]`` will inhibit the insertion of these
9226	instrumentation points.
9227
9228	If a function has neither of these attributes, they become subject to the XRay
9229	heuristics used to determine whether a function should be instrumented or
9230	otherwise.
9231
9232	``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is
9233	used to preserve N function arguments for the logging function. Currently,
9234	only N==1 is supported.)reST";
9235
9236	static const char AttrDoc_XRayLogArgs[] = R"reST(``__attribute__((xray_always_instrument))`` or
9237	``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++),
9238	methods (in Objective C), and free functions (in C, C++, and Objective C) to be
9239	instrumented with XRay. This will cause the function to always have space at
9240	the beginning and exit points to allow for runtime patching.
9241
9242	Conversely, ``__attribute__((xray_never_instrument))`` or
9243	``[[clang::xray_never_instrument]]`` will inhibit the insertion of these
9244	instrumentation points.
9245
9246	If a function has neither of these attributes, they become subject to the XRay
9247	heuristics used to determine whether a function should be instrumented or
9248	otherwise.
9249
9250	``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is
9251	used to preserve N function arguments for the logging function. Currently,
9252	only N==1 is supported.)reST";
9253
9254	static const char AttrDoc_ZeroCallUsedRegs[] = R"reST(This attribute, when attached to a function, causes the compiler to zero a
9255	subset of all call-used registers before the function returns. It's used to
9256	increase program security by either mitigating `Return-Oriented Programming`_
9257	(ROP) attacks or preventing information leakage through registers.
9258
9259	The term "call-used" means registers which are not guaranteed to be preserved
9260	unchanged for the caller by the current calling convention. This could also be
9261	described as "caller-saved" or "not callee-saved".
9262
9263	The `choice` parameters gives the programmer flexibility to choose the subset
9264	of the call-used registers to be zeroed:
9265
9266	- ``skip`` doesn't zero any call-used registers. This choice overrides any
9267	command-line arguments.
9268	- ``used`` only zeros call-used registers used in the function. By ``used``, we
9269	mean a register whose contents have been set or referenced in the function.
9270	- ``used-gpr`` only zeros call-used GPR registers used in the function.
9271	- ``used-arg`` only zeros call-used registers used to pass arguments to the
9272	function.
9273	- ``used-gpr-arg`` only zeros call-used GPR registers used to pass arguments to
9274	the function.
9275	- ``all`` zeros all call-used registers.
9276	- ``all-gpr`` zeros all call-used GPR registers.
9277	- ``all-arg`` zeros all call-used registers used to pass arguments to the
9278	function.
9279	- ``all-gpr-arg`` zeros all call-used GPR registers used to pass arguments to
9280	the function.
9281
9282	The default for the attribute is controlled by the ``-fzero-call-used-regs``
9283	flag.
9284
9285	.. _Return-Oriented Programming: https://en.wikipedia.org/wiki/Return-oriented_programming)reST";
9286

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