std/core/src/attribute_docs.rs
1#[doc(attribute = "must_use")]
2//
3/// Warn when a value is ignored.
4///
5/// The `must_use` attribute applies to values where simply creating or returning them is
6/// often not enough. If a value marked with `#[must_use]` is produced and then ignored, the
7/// compiler warns through the [`unused_must_use`] lint.
8///
9/// This is most common on types that represent an important state or outcome. For example,
10/// [`Result`] is marked `#[must_use]` because ignoring an error value can hide a failed operation.
11/// In the following example, the returned [`Result`] is the only sign that writing the message
12/// might have failed:
13///
14/// ```
15/// # #![allow(unused_must_use)]
16/// fn write_message() -> std::io::Result<()> {
17/// // Write the message...
18/// Ok(())
19/// }
20///
21/// write_message();
22/// ```
23///
24/// Ignoring that [`Result`] triggers this warning:
25///
26/// ```text
27/// warning: unused `Result` that must be used
28/// = note: this `Result` may be an `Err` variant, which should be handled
29/// = note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
30/// help: use `let _ = ...` to ignore the resulting value
31/// ```
32///
33/// Future values are also `#[must_use]`: creating a future does not run it, so ignoring one often
34/// means the intended asynchronous work never happens.
35///
36/// You can also place `#[must_use]` on a function, method, or trait declaration. On a function or
37/// method, the warning is tied to ignoring that call's return value:
38///
39/// ```
40/// # #![allow(unused_must_use)]
41/// #[must_use]
42/// fn make_token() -> String {
43/// String::from("token")
44/// }
45///
46/// // Ignoring this call's return value triggers `unused_must_use`.
47/// make_token();
48/// ```
49///
50/// On a trait, the warning applies when a function returns an opaque type (`impl Trait`) or trait
51/// object (`dyn Trait`) whose bounds include that trait. This is how futures warn if you create one
52/// but never poll or await it, since an `async fn` returns an opaque type implementing [`Future`].
53///
54/// The attribute can include a message explaining what the caller should do with the value:
55///
56/// ```
57/// # #![allow(dead_code)]
58/// #[must_use = "call `.finish()` to complete the operation"]
59/// fn start_operation() -> Operation {
60/// Operation
61/// }
62///
63/// struct Operation;
64/// ```
65///
66/// If intentionally ignoring the value is correct, bind it to `_` or call [`drop`]:
67///
68/// ```
69/// # #[must_use]
70/// # fn make_token() -> String {
71/// # String::from("token")
72/// # }
73/// let _ = make_token();
74/// drop(make_token());
75/// ```
76///
77/// The attribute is a warning tool, not a type-system rule. Code can still explicitly discard a
78/// `#[must_use]` value, and the compiler does not require callers to inspect or otherwise act on
79/// the value.
80///
81/// For more information, see the Reference on [the `must_use` attribute].
82///
83/// [`unused_must_use`]: ../rustc/lints/listing/warn-by-default.html#unused-must-use
84/// [the `must_use` attribute]: ../reference/attributes/diagnostics.html#the-must_use-attribute
85const _: () = ();
86
87#[doc(attribute = "allow")]
88//
89/// The `allow` attribute suppresses lint diagnostics that would otherwise produce
90/// warnings or errors. It can be used on any lint or lint group (except those
91/// set to [`forbid`]).
92///
93/// ```
94/// #[allow(dead_code)]
95/// fn unused_function() {
96/// // ...
97/// }
98///
99/// fn main() {
100/// // `unused_function` does not generate a compiler warning.
101/// }
102/// ```
103///
104/// Without `#[allow(dead_code)]`, the example above would emit:
105///
106/// ```text
107/// warning: function `unused_function` is never used
108/// --> main.rs:1:4
109/// |
110/// 1 | fn unused_function() {
111/// | ^^^^^^^^^^^^^^^
112/// |
113/// = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default
114///
115/// warning: 1 warning emitted
116/// ```
117///
118/// Multiple lints can be set to `allow` at once with commas:
119///
120/// ```
121/// #[allow(unused_variables, unused_mut)]
122/// fn main() {
123/// let mut x: u32 = 42;
124/// }
125/// ```
126///
127/// This is mostly used to prevent lint warnings or errors while still under development.
128///
129/// It cannot override a lint that has been set to [`forbid`].
130///
131/// It's also important to consider that overusing `allow` could make code harder to maintain
132/// and possibly hide issues. To mitigate this issue, using the `expect` attribute is preferred.
133///
134/// `allow` can be overridden by [`warn`], [`deny`], and [`forbid`].
135///
136/// The lint checks supported by rustc can be found via `rustc -W help`,
137/// along with their default settings and are documented in [the `rustc` book].
138///
139/// [the `rustc` book]: ../rustc/lints/listing/index.html
140///
141/// For more information, see the Reference on [the `allow` attribute].
142///
143/// [the `allow` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes
144/// [`forbid`]: ./attribute.forbid.html
145/// [`warn`]: ./attribute.warn.html
146/// [`deny`]: ./attribute.deny.html
147const _: () = ();
148
149#[doc(attribute = "cfg")]
150//
151/// Used for conditional compilation.
152///
153/// The `cfg` attribute allows compiling an item under specific conditions, otherwise it
154/// will be ignored.
155///
156/// ```
157/// // Only compiles this function for Linux.
158/// #[cfg(target_os = "linux")]
159/// fn platform_specific() {
160/// println!("Running on Linux");
161/// }
162///
163/// // Only compiles this function if not for Linux.
164/// #[cfg(not(target_os = "linux"))]
165/// fn platform_specific() {
166/// println!("Running on something else");
167/// }
168/// ```
169///
170/// Depending on the platform you're targeting, only one of these two functions will be considered
171/// during the compilation.
172///
173/// Conditions can also be combined with `all(...)`, `any(...)`, and `not(...)`:
174///
175/// * `all`: True if all given predicates are true.
176/// * `any`: True if at least one of the given predicates is true.
177/// * `not`: True if the predicate is false and false if the predicate is true.
178///
179/// ```
180/// #[cfg(all(unix, target_pointer_width = "64"))]
181/// fn unix_64bit() {
182/// // ...
183/// }
184/// ```
185///
186/// If you want to use this mechanism in an [`if`] condition in your code, you
187/// can use the [`cfg!`] macro. To conditionally apply an attribute,
188/// see [`cfg_attr`].
189///
190/// For more information, see the Reference on [the `cfg` attribute].
191///
192/// [`cfg_attr`]: ./attribute.cfg_attr.html
193/// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute
194/// [`if`]: ./keyword.if.html
195const _: () = ();
196
197#[doc(attribute = "crate_name")]
198//
199/// Specifies the name of the crate.
200///
201/// Written as an inner attribute at the top of the crate root, `crate_name` is used
202/// to specify the name of a crate.
203///
204/// ```
205/// #![crate_name = "my_crate"]
206/// ```
207///
208/// The crate name must not be empty, and must only contain [Unicode alphanumeric] or
209/// `_` (U+005F) characters.
210///
211/// Note that the specified name must match the name given by the `--crate-name` flag.
212///
213/// ```text
214/// error: `--crate-name` and `#[crate_name]` are required to match, but `cli_name` != `attr_name`
215/// --> main.rs:1:17
216/// |
217/// 1 | #![crate_name = "attr_name"]
218/// | ^^^^^^^^^^^
219/// ```
220///
221/// In a Cargo project the crate name is always passed as `--crate-name`, derived from the target
222/// name (`[lib] name` or `[[bin]] name` if set, otherwise `[package] name` for libraries and the
223/// primary binary, or the source file name for other binaries). The `crate_name` attribute is
224/// therefore redundant here: it adds nothing, and if it is present it must match Cargo's name,
225/// otherwise `rustc` reports an error.
226///
227/// For more information, see the Reference on [the `crate_name` attribute].
228///
229/// [Unicode alphanumeric]: ../std/primitive.char.html#method.is_alphanumeric
230/// [the `crate_name` attribute]: ../reference/crates-and-source-files.html#the-crate_name-attribute
231const _: () = ();
232
233#[doc(attribute = "crate_type")]
234//
235/// Specifies the type of a crate.
236///
237/// Written as an inner attribute at the top of the crate root, `crate_type` is used
238/// to specify the type of a crate.
239///
240/// ```
241/// #![crate_type = "lib"]
242/// ```
243///
244/// The specified crate type must be a known crate type (for the list of valid crate types, see [Linkage]),
245/// otherwise `rustc` reports an error:
246///
247/// ```text
248/// error: invalid `crate_type` value
249/// --> typo.rs:1:17
250/// |
251/// 1 | #![crate_type = "dyllib"]
252/// | ^^^^^^^^ help: did you mean: `"dylib"`
253/// |
254/// = note: `#[deny(unknown_crate_types)]` on by default
255/// ```
256///
257/// In one session of compilation, the compiler can generate multiple artifacts through the use of
258/// either command line flags or the `crate_type` attribute. Note that the output artifacts are stackable in
259/// the sense that if multiple are specified, then the compiler will produce each form of output without
260/// having to recompile.
261///
262/// For example, if a crate has the following `crate_type` attributes:
263///
264/// ```
265/// #![crate_type = "staticlib"]
266/// #![crate_type = "dylib"]
267/// ```
268///
269/// Then the compiler will build both a static library and a dynamic library.
270///
271/// If the flag `--test` is passed, the `crate_type` attributes will be ignored, and the crate will be built
272/// as a test harness.
273///
274/// For `[lib]`/`[[bin]]` targets Cargo passes `--crate-type` derived from the target (`[lib] crate-type`, `[[bin]]`);
275/// test/bench targets are compiled with `--test`. In all these cases the attribute is ignored.
276///
277/// Note that the `bin` type and `proc-macro` type cannot be mixed with any other crate type,
278/// otherwise `rustc` reports an error:
279///
280/// ```text
281/// error: cannot mix `bin` crate type with others
282/// ```
283///
284/// ```text
285/// error: cannot mix `proc-macro` crate type with others
286/// ```
287///
288/// In general, crate type `bin` and crate type `lib` should be sufficient for all compilation needs, and
289/// the other options are just available if more fine-grained control is desired over the output format of
290/// a crate.
291///
292/// For more information, see the Reference on [Linkage].
293///
294/// [Linkage]: ../reference/linkage.html
295const _: () = ();
296
297#[doc(attribute = "deny")]
298//
299/// Emits an error, preventing the compilation from finishing, when a lint check has failed.
300/// This is useful for enforcing rules or preventing certain patterns:
301///
302/// ```compile_fail
303/// #[deny(unused)]
304/// fn foo() {
305/// let x = 42; // Emits an error because x is unused.
306/// }
307/// ```
308///
309/// `deny` can be overridden by [`allow`], [`warn`], and [`forbid`]:
310///
311/// ```
312/// #![deny(unused)]
313///
314/// #[allow(unused)] // We override the `deny` for this function.
315/// fn foo() {
316/// let x = 42; // No lint emitted even though `x` is unused.
317/// }
318/// ```
319///
320/// Multiple lints can also be set to `deny` at once:
321///
322/// ```compile_fail
323/// #![deny(unused_imports, unused_variables)]
324/// use std::collections::*;
325///
326/// fn main() {
327/// let mut x = 10;
328/// }
329/// ```
330///
331/// The lint checks supported by rustc can be found via `rustc -W help`,
332/// along with their default settings and are documented in [the `rustc` book].
333///
334/// [the `rustc` book]: ../rustc/lints/listing/index.html
335///
336/// For more information, see the Reference on [the `deny` attribute].
337///
338/// [the `deny` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes
339/// [`forbid`]: ./attribute.forbid.html
340/// [`allow`]: ./attribute.allow.html
341/// [`warn`]: ./attribute.warn.html
342/// [`deny`]: ./attribute.deny.html
343const _: () = ();
344
345#[doc(attribute = "forbid")]
346//
347/// Emits an error, preventing the compilation from finishing, when a lint check has failed.
348///
349/// A lint set to `forbid` cannot be overridden by [`allow`] or [`warn`].
350/// Attempting either will result in a compilation error. Writing `#[deny(...)]` on the same lint inside a
351/// `forbid` scope is permitted, but has no effect; the lint remains at the `forbid` level.
352///
353/// This is useful for enforcing strict policies that should not be relaxed
354/// anywhere in the codebase. Example:
355///
356/// ```
357/// #![forbid(unsafe_code)]
358///
359/// // This would cause a compilation error if uncommented:
360/// // #[allow(unsafe_code)] // error: cannot override `forbid`
361/// ```
362///
363/// Multiple lints can be set to `forbid` at once:
364///
365/// ```
366/// #![forbid(unsafe_code, unused)]
367/// ```
368///
369/// The lint checks supported by rustc can be found via `rustc -W help`,
370/// along with their default settings and are documented in [the `rustc` book].
371///
372/// [the `rustc` book]: ../rustc/lints/listing/index.html
373///
374/// For more information, see the Reference on [the `forbid` attribute].
375///
376/// [the `forbid` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes
377/// [`allow`]: ./attribute.allow.html
378/// [`warn`]: ./attribute.warn.html
379const _: () = ();
380
381#[doc(attribute = "deprecated")]
382//
383/// Emits a warning during compilation when an item with this attribute is used.
384/// `since` and `note` are optional fields giving more detail about why the item is deprecated.
385///
386/// * `since`: the version since when the item is deprecated.
387/// * `note`: the reason why an item is deprecated.
388///
389/// Example:
390///
391/// ```
392/// #[deprecated(since = "1.0.0", note = "Use bar instead")]
393/// struct Foo;
394/// struct Bar;
395/// ```
396///
397/// The `deprecated` attribute helps developers transition away from old code by providing warnings
398/// when deprecated items are used. Note that during `Cargo` builds, warnings on dependencies get
399/// silenced by default, so you may not see a deprecation warning unless you build that dependency
400/// directly.
401///
402/// For more information, see the Reference on [the `deprecated` attribute].
403///
404/// [the `deprecated` attribute]: ../reference/attributes/diagnostics.html#the-deprecated-attribute
405const _: () = ();
406
407#[doc(attribute = "warn")]
408//
409/// Emits a warning during compilation when a lint check failed.
410///
411/// Unlike [`deny`] or [`forbid`], `warn` does not produce a hard error: the compilation
412/// continues, but the compiler emits a warning message. `warn` can be overridden by [`allow`],
413/// [`deny`], and [`forbid`].
414///
415/// Example:
416///
417/// ```compile_fail
418/// #![allow(unused)]
419///
420/// #[warn(unused)] // We override the allowed `unused` lint.
421/// fn foo() {
422/// // This lint warns by default even without #[warn(unused)] being explicitly set
423/// let x = 42; // warning: unused variable `x`
424/// }
425/// ```
426///
427///
428/// Many lints, including `unused`, are already set to `warn` by default so this attribute is
429/// mainly useful for lints that are normally [`allow`] by default.
430///
431/// Multiple lints can be set to `warn` at once:
432///
433/// ```compile_fail
434/// #[warn(unused_mut, unused_variables)]
435/// fn main() {
436/// let mut x = 42;
437/// }
438/// ```
439///
440/// The lint checks supported by rustc can be found via `rustc -W help`,
441/// along with their default settings and are documented in [the `rustc` book].
442///
443/// [the `rustc` book]: ../rustc/lints/listing/index.html
444///
445/// For more information, see the Reference on [the `warn` attribute].
446///
447/// [the `warn` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes
448/// [`allow`]: ./attribute.allow.html
449/// [`deny`]: ./attribute.deny.html
450/// [`forbid`]: ./attribute.forbid.html
451const _: () = ();
452
453#[doc(attribute = "no_std")]
454//
455/// Prevents automatically linking the standard library.
456///
457/// Written as an inner attribute at the top of the crate root, the `no_std` attribute stops
458/// the compiler from linking [`std`] into the crate, and only links [`core`].
459///
460/// The attribute also swaps which prelude gets inserted, with the [`core`] prelude replacing
461/// the [`std`] prelude. Items like [`Option`], [`Result`], and the primitive types remain
462/// available from [`core`] without any imports needed:
463///
464/// ```rust,ignore (no_std)
465/// #![no_std]
466///
467/// fn halve(x: u32) -> Option<u32> {
468/// if x % 2 == 0 { Some(x / 2) } else { None }
469/// }
470/// ```
471///
472/// Anything that requires heap memory allocations is not part of [`core`]. Linking the [`alloc`]
473/// crate explicitly can be used to include these types:
474///
475/// ```rust,ignore (no_std + needs a global allocator to link)
476/// #![no_std]
477///
478/// extern crate alloc;
479///
480/// use alloc::vec::Vec;
481/// ```
482///
483/// A `no_std` binary also removes the startup routine and default panic handler `std`
484/// normally provides. It must define its own `#[panic_handler]`, and typically its own
485/// entry point by additionally using `#![no_main]`:
486///
487/// ```rust,ignore (no_std + needs more than no_main alone to link)
488/// #![no_std]
489/// #![no_main]
490///
491/// use core::panic::PanicInfo;
492///
493/// #[panic_handler]
494/// fn on_panic(_info: &PanicInfo) -> ! {
495/// loop {}
496/// }
497/// ```
498///
499/// For more information, see the Reference on [the `no_std` attribute].
500///
501/// [`std`]: ../std/index.html
502/// [`core`]: ../core/index.html
503/// [`alloc`]: ../alloc/index.html
504/// [`Option`]: option::Option
505/// [`Result`]: result::Result
506/// [the `no_std` attribute]: ../reference/names/preludes.html#the-no_std-attribute
507const _: () = ();
508
509#[doc(attribute = "no_main")]
510/// Prevents emitting the `main` entrypoint symbol.
511///
512/// Written as an inner attribute at the top of the crate root, the `no_main` attribute prevents
513/// the compiler from generating the program's standard Rust entrypoint, leaving that up to you.
514/// This is useful when some other object being linked into the program defines the entrypoint,
515/// or when you want to define the platform's `main` symbol yourself.
516///
517/// If you define an entry point symbol that is suitable for your target, it must also be exported
518/// under an unmangled name using the [`no_mangle` attribute]:
519///
520/// ```no_run
521/// #![no_main]
522///
523/// use std::ffi::{c_char, c_int};
524///
525/// #[unsafe(no_mangle)]
526/// pub extern "C" fn main(_argc: c_int, _argv: *const *const c_char) -> c_int {
527/// println!("Hello world!");
528/// 0
529/// }
530/// ```
531///
532/// Unlike `no_std`, the `no_main` attribute does not prevent the compiler from generating
533/// the startup routine or linking the standard library provided by the operating system's executable [ABI].
534///
535/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
536/// [`no_mangle` attribute]: ../reference/abi.html#the-no_mangle-attribute
537const _: () = ();
538
539#[doc(attribute = "repr")]
540/// Specifies the [representation] of a type.
541///
542/// Written as an outer attribute on a `struct`, `enum` or `union`, `repr` controls how the
543/// type is laid out in memory. This is needed when passing types across an [FFI] boundary
544/// or whenever you rely on a specific layout.
545///
546/// The available representations are:
547///
548/// * [`Rust`] (the default): the layout is unspecified and may change between compilations.
549/// * [`C`]: the layout follows the rules of the C language for the target platform.
550/// * The [primitive representations] (`u8`, `i32`, `usize`, ...): set the discriminant
551/// type of an enum.
552/// * [`transparent`]: the type has the same layout and ABI as its only non-zero-sized field.
553///
554/// The `align(N)` and `packed(N)` modifiers raise or lower the alignment of a type, respectively.
555/// `N` must be a power of two no greater than 2<sup>29</sup>. The two modifiers cannot be
556/// applied to the same type, and references to fields of a `packed` type cannot be created,
557/// since they may be unaligned.
558///
559/// # Examples
560///
561/// ```
562/// #[repr(C, align(16))]
563/// struct Foo {
564/// first: u32,
565/// second: u32,
566/// third: u32,
567/// }
568///
569/// assert_eq!(align_of::<Foo>(), 16);
570/// // 12 bytes of fields, rounded up to a multiple of the alignment.
571/// assert_eq!(size_of::<Foo>(), 16);
572/// ```
573///
574/// ```
575/// #[repr(C, packed(2))]
576/// struct Foo {
577/// first: u32,
578/// second: u32,
579/// third: u32,
580/// }
581///
582/// assert_eq!(align_of::<Foo>(), 2);
583/// assert_eq!(size_of::<Foo>(), 12);
584/// ```
585///
586/// ```
587/// #[repr(C)]
588/// struct Foo<T> {
589/// item: T,
590/// }
591/// ```
592///
593/// `Foo` is laid out according to the C rules and is guaranteed to be 16-byte aligned.
594///
595/// The representation is a property of the type definition, so it does
596/// parameters: below, `Foo<u8>` and `Foo<u64>` both use the `C` representation. Their actual
597/// layouts still differ, because they depend on `T`.
598///
599/// [representation]: ../reference/type-layout.html#representations
600/// [`Rust`]: ../reference/type-layout.html#the-rust-representation
601/// [`C`]: ../reference/type-layout.html#the-c-representation
602/// [primitive representations]: ../reference/type-layout.html#primitive-representations
603/// [`transparent`]: ../reference/type-layout.html#the-transparent-representation
604/// [FFI]: https://en.wikipedia.org/wiki/Foreign_function_interface
605const _: () = ();
606
607#[doc(attribute = "inline")]
608//
609/// Suggest that the compiler inline a function at its call sites.
610///
611/// Inlining replaces a call with a copy of the called function's body, which can remove the
612/// overhead of the call. The `inline` attribute is only a hint: the compiler may ignore it, and
613/// it already inlines functions on its own when that looks worthwhile. Poor choices about what to
614/// inline can make a program larger or slower.
615///
616/// Where it does matter is inlining across crate boundaries. A non-generic function is not
617/// normally inlined into another crate, since the calling crate compiles against only its
618/// signature. Marking it `#[inline]` makes the body available to other crates so they can inline
619/// it too:
620///
621/// ```rust
622/// # #![allow(dead_code)]
623/// #[inline]
624/// pub fn square(x: i32) -> i32 {
625/// x * x
626/// }
627/// ```
628///
629/// Generic functions do not need this. They are instantiated in each crate that uses them, so
630/// their bodies are already available to inline.
631///
632/// The attribute applies to functions and has three forms:
633///
634/// - `#[inline]` suggests inlining the function.
635/// - `#[inline(always)]` suggests inlining it at every call site.
636/// - `#[inline(never)]` suggests never inlining it.
637///
638/// You should almost never need `#[inline(always)]`: prefer to let the compiler decide unless
639/// profiling shows a small, hot function that benefits from it. `#[inline(never)]` is useful to
640/// keep a rarely used path, such as a function that only reports an error, out of its caller.
641///
642/// For more information, see the Reference on [the `inline` attribute].
643///
644/// [the `inline` attribute]: ../reference/attributes/codegen.html#the-inline-attribute
645const _: () = ();
646
647#[doc(attribute = "cold")]
648//
649/// Hint to the compiler that a function is unlikely to be called.
650///
651/// Marking a function `#[cold]` tells the compiler that calls to it are rare, so it can
652/// optimize for the common case where the function is not called. It is only a hint: the
653/// compiler may ignore it, and it does not change the function's behavior.
654///
655/// It is typically used on functions that handle uncommon cases, such as error or panic paths:
656///
657/// ```rust
658/// # #![allow(dead_code)]
659/// fn check(value: i32) {
660/// if value < 0 {
661/// report_error("value must be non-negative");
662/// }
663/// // ... the common case continues here ...
664/// }
665///
666/// #[cold]
667/// fn report_error(message: &str) {
668/// eprintln!("error: {message}");
669/// }
670/// ```
671///
672/// For more information, see the Reference on [the `cold` attribute].
673///
674/// [the `cold` attribute]: ../reference/attributes/codegen.html#the-cold-attribute
675const _: () = ();
676
677#[doc(attribute = "track_caller")]
678//
679/// Make a function report the location of its caller instead of its own.
680///
681/// When a function panics, the panic message normally points at the line inside that function
682/// where the panic happened. `#[track_caller]` changes that: it lets the function see the
683/// [`Location`] it was called from, so the panic (and any direct use of [`Location::caller`])
684/// points at the call site instead. The standard library uses this on methods like
685/// [`Option::unwrap`], so a failed `unwrap` blames the line that called it rather than a line
686/// inside the standard library.
687///
688/// ```rust,should_panic
689/// #[track_caller]
690/// fn assert_even(n: i32) {
691/// assert!(n % 2 == 0, "{n} is not even");
692/// }
693///
694/// // The panic blames this line, not the `assert!` inside `assert_even`.
695/// assert_even(3);
696/// ```
697///
698/// The attribute applies to functions with the default `"Rust"` ABI, other than `fn main`.
699///
700/// For more information, see the Reference on [the `track_caller` attribute].
701///
702/// [`Location`]: panic::Location
703/// [`Location::caller`]: panic::Location::caller
704/// [`Option::unwrap`]: Option::unwrap
705/// [the `track_caller` attribute]: ../reference/attributes/codegen.html#the-track_caller-attribute
706const _: () = ();
707
708#[doc(attribute = "proc_macro")]
709//
710/// Defines a function-like procedural macro.
711///
712/// Applied to a `pub` function at the root of a proc-macro crate, `proc_macro` makes that function usable as a macro invoked as
713/// `foo!(...)` in other crates. The function receives the tokens written inside the invocation as a [`TokenStream`] and returns
714/// the [`TokenStream`] that replaces the invocation:
715///
716/// ```rust, ignore (requires depending on the proc-macro crate)
717/// # extern crate proc_macro;
718/// use proc_macro::TokenStream;
719///
720/// #[proc_macro]
721/// pub fn foo(input: TokenStream) -> TokenStream {
722/// "fn answer() -> u32 { 67 }".parse().unwrap()
723/// }
724/// ```
725///
726/// The macro can only be invoked from other crates, not from the crate where it is defined:
727///
728/// ```rust,ignore (requires depending on the proc-macro crate)
729/// use my_macro_crate::foo;
730///
731/// // Expands to `fn answer() -> u32 { 67 }`.
732/// foo!();
733///
734/// fn main() {
735/// println!("{}", answer()); // Prints 67
736/// }
737/// ```
738///
739/// The attribute is only usable with crates of the `proc-macro` crate type, which is set in the crate's `Cargo.toml`
740/// with `proc-macro = true` in the `[lib]` section. Using it anywhere else is a compilation error:
741///
742/// ```text
743///error: the `#[proc_macro]` attribute is only usable with crates of the `proc-macro` crate type
744/// --> src/lib.rs:4:1
745/// |
746/// 4| #[proc_macro]
747/// | ^^^^^^^^^^^^
748/// ```
749///
750/// For more information, see the Reference on [function-like procedural macros] and the [`proc_macro`] crate documentation.
751///
752/// [`TokenStream`]: ../proc_macro/struct.TokenStream.html
753/// [function-like procedural macros]: ../reference/procedural-macros.html#the-proc_macro-attribute
754/// [`proc_macro`]: ../proc_macro/index.html
755const _: () = ();
756
757#[doc(attribute = "link_section")]
758//
759/// Places a function or static in a specific object-file section.
760///
761/// The `link_section` attribute specifies the section of the generated object file where a
762/// function or static is placed. Section names and their meaning are target-specific.
763///
764/// ```rust,no_run
765/// # #[cfg(target_os = "linux")] {
766/// #[unsafe(link_section = ".example_section")]
767/// pub static VALUE: u32 = 42;
768/// # }
769/// ```
770///
771/// Incorrectly placing code or data in a section can violate requirements imposed by the target,
772/// linker, or runtime. For example, placing mutable data in a read-only section may result in
773/// undefined behavior. For this reason, `link_section` is an unsafe attribute.
774///
775/// Starting with the 2024 edition, the attribute must be written using the `unsafe(...)` syntax.
776/// Earlier editions also permit `#[link_section = "..."]`.
777///
778/// For more information, see the Reference on [the `link_section` attribute].
779///
780/// [the `link_section` attribute]: ../reference/abi.html#the-link_section-attribute
781const _: () = ();
782
783#[doc(attribute = "non_exhaustive")]
784//
785/// Indicates that a type might have more fields or variants added in the future.
786///
787/// Placing `#[non_exhaustive]` on a struct or enum tells code in other crates not to assume
788/// the definition is complete. This lets a library add new fields or variants without breaking
789/// existing code.
790///
791/// On an enum, code outside the defining crate must include a wildcard arm when matching:
792///
793/// ```rust,ignore (cross-crate effect only)
794/// // in crate `errors`:
795/// #[non_exhaustive]
796/// pub enum ConnectionError {
797/// Refused,
798/// Timeout,
799/// }
800///
801/// // in another crate:
802/// use errors::ConnectionError;
803///
804/// match error {
805/// ConnectionError::Refused => println!("connection refused"),
806/// ConnectionError::Timeout => println!("timed out"),
807/// _ => println!("other error"), // required because of #[non_exhaustive]
808/// }
809/// ```
810///
811/// On a struct, code outside the defining crate cannot construct instances using struct literal
812/// syntax:
813///
814/// ```rust,ignore (cross-crate effect only)
815/// // in crate `config`:
816/// #[non_exhaustive]
817/// pub struct Config {
818/// pub width: u32,
819/// pub height: u32,
820/// }
821///
822/// // in another crate:
823/// use config::Config;
824///
825/// let c = Config { width: 800, height: 600 }; // ERROR: cannot construct
826/// ```
827///
828/// Inside the defining crate, exhaustive matching and direct construction are still allowed.
829///
830/// For more information, see the Reference on [the `non_exhaustive` attribute].
831///
832/// [the `non_exhaustive` attribute]: ../reference/attributes/type_system.html#the-non_exhaustive-attribute
833const _: () = ();
834
835#[doc(attribute = "automatically_derived")]
836//
837/// The `automatically_derived` attribute is used to indicate that an `impl` block is automatically
838/// generated by a [derive macro]. It has no direct effect, but it may be used by tools and
839/// diagnostic lints, such as [Clippy], to detect these automatically generated implementations.
840///
841/// Example:
842///
843/// ```rust
844/// // Given #[derive(Clone)] on struct Example, the derive macro may produce:
845/// #[automatically_derived]
846/// impl ::core::clone::Clone for Example {
847/// fn clone(&self) -> Self { Example }
848/// }
849/// # struct Example;
850/// ```
851///
852/// The attribute may only be applied to an `impl` block.
853///
854/// Because code generated by a macro becomes part of the source code representation of the crate
855/// that calls the macro, diagnostic lints for the expanded macro will be emitted in the caller's
856/// workspace (whereas warnings generated while building dependencies not in the local workspace
857/// are suppressed by Cargo). This may be undesirable, so the author of the macro can use the
858/// `automatically_derived` attribute to hint to tools that the generated code is not written by the
859/// caller (and that tools should not render warnings for it).
860///
861/// For example, this `impl` block lacks `#[automatically_derived]`:
862///
863/// ```rust
864/// // Suppose this impl block is the output of a derive macro
865/// impl ::core::cmp::PartialEq for Example {
866/// fn eq(&self, other: &Self) -> bool { true }
867/// fn ne(&self, other: &Self) -> bool { !(self == other) }
868/// }
869/// # struct Example;
870/// ```
871///
872/// In the example above, Clippy will emit the following warning:
873///
874/// ```text
875/// warning: re-implementing `PartialEq::ne` is unnecessary
876/// --> src/lib.rs:7:9
877/// |
878/// 4 | fn ne(&self, other: &Self) -> bool { !(self == other) }
879/// | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
880/// |
881/// = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.98.0/index.html#partialeq_ne_impl
882/// = note: `#[warn(clippy::partialeq_ne_impl)]` on by default
883/// ```
884///
885/// However, if the derive macro were written so that it outputs `#[automatically_derived]` on the
886/// `impl` block, as below, then Clippy will not emit the above `partialeq_ne_impl` lint:
887///
888/// ```rust
889/// // Suppose this impl block is the output of a derive macro
890/// #[automatically_derived]
891/// impl ::core::cmp::PartialEq for Example {
892/// fn eq(&self, other: &Self) -> bool { true }
893/// fn ne(&self, other: &Self) -> bool { !(self == other) }
894/// }
895/// # struct Example;
896/// ```
897///
898/// The `automatically_derived` attribute should be preferred over the [`allow`] attribute for
899/// suppressing unintended user-facing diagnostics in automatically generated code.
900///
901/// For more information, see the Reference on [the `automatically_derived` attribute].
902///
903/// [`allow`]: ./attribute.allow.html
904/// [derive macro]: ./attr.derive.html
905/// [Clippy]: https://github.com/rust-lang/rust-clippy
906/// [the `automatically_derived` attribute]: ../reference/attributes/derive.html#the-automatically_derived-attribute
907const _: () = ();
908
909#[doc(attribute = "cfg_attr")]
910//
911/// The `cfg_attr` attribute is used to conditionally apply one or more attributes to an item.
912///
913/// Example:
914///
915/// ```rust
916/// // The struct derives `Debug` when the `debug_impls` feature is enabled.
917/// #[cfg_attr(feature = "debug_impls", derive(Debug))]
918/// struct X;
919/// ```
920///
921/// You can apply multiple attributes by separating them with commas:
922///
923/// ```rust
924/// #[cfg_attr(feature = "nightly", allow(dead_code), deny(unused_variables))]
925/// // This function only gets the `allow(dead_code)` and `deny(unused_variables)` attributes when
926/// // `feature = "nightly"` is active.
927/// fn nightly_only_function() {
928/// let x = 42;
929/// }
930/// ```
931///
932/// For complex conditions, you can combine `all(...)`, `any(...)`, and `not(...)`.
933///
934/// * `all`: True if all given predicates are true.
935/// * `any`: True if at least one of the given predicates is true.
936/// * `not`: True if the predicate is false.
937///
938/// ```rust
939/// #[cfg_attr(
940/// all(feature = "system", feature = "disk"),
941/// doc = "These docs only show up if both `system`, and `disk` are enabled.",
942/// )]
943/// mod my_module {
944/// // ...
945/// }
946/// ```
947///
948/// For more information, see the Reference on [the `cfg_attr` attribute].
949///
950/// [`cfg`]: ./attribute.cfg.html
951/// [the `cfg_attr` attribute]: ../reference/conditional-compilation.html#the-cfg_attr-attribute
952const _: () = ();
953
954#[doc(attribute = "windows_subsystem")]
955//
956/// The `windows_subsystem` attribute is used to specify the subsystem for a Windows application.
957///
958/// Example:
959///
960/// ```rust
961/// #![windows_subsystem = "windows"]
962///
963/// fn main() {}
964/// ```
965///
966/// Accepted values are "console" (default) and "windows".
967///
968/// The `windows_subsystem` attribute may only be applied to the crate root.
969///
970/// Only the first use of `windows_subsystem` has effect.
971///
972/// The `windows_subsystem` attribute is ignored on non-Windows targets and non-bin crate types.
973/// If a "console" process is run from an existing console then it will be attached to said console;
974/// otherwise a new one will be created.
975/// The "windows" subsystem will run detached from any existing "console".
976///
977/// [Reference](../reference/runtime.html#the-windows_subsystem-attribute)
978const _: () = ();
979
980#[doc(attribute = "recursion_limit")]
981//
982/// Sets the maximum depth for recursive compile-time operations.
983///
984/// The compiler limits how deeply it recurses while performing operations that could
985/// otherwise expand forever, such as macro expansion and auto-dereference. The
986/// `recursion_limit` attribute raises that limit. It applies to the whole crate and is
987/// written at the crate root:
988///
989/// ```
990/// #![recursion_limit = "256"]
991///
992/// // Macros may now expand up to 256 levels deep.
993/// ```
994///
995/// The value is a string containing the new limit. The default is 128.
996///
997/// This limit affects only compile-time recursion. It does not change how deeply
998/// recursive code can run at runtime.
999///
1000/// When a compile-time operation recurses deeper than the limit, compilation fails. For
1001/// example, this macro expands itself forever, so it always hits the limit:
1002///
1003/// ```compile_fail
1004/// macro_rules! a {
1005/// () => { a!(); };
1006/// }
1007///
1008/// a!();
1009/// ```
1010///
1011/// This produces an error whose help message suggests how to raise the limit:
1012///
1013/// ```text
1014/// error: recursion limit reached while expanding `a!`
1015/// --> src/main.rs:2:13
1016/// |
1017/// 2 | () => { a!(); };
1018/// | ^^^^
1019/// ...
1020/// 5 | a!();
1021/// | ---- in this macro invocation
1022/// |
1023/// = help: consider increasing the recursion limit by adding a `#![recursion_limit = "256"]`
1024/// attribute to your crate
1025/// ```
1026///
1027/// Auto-dereference is limited in the same way:
1028///
1029/// ```compile_fail
1030/// #![recursion_limit = "1"]
1031///
1032/// // Error: two recursive steps are needed to auto-dereference `&&&1` to `&u8`.
1033/// let f = |_: &u8| {};
1034/// f(&&&1);
1035/// ```
1036///
1037/// Reaching the limit is most common in code that nests many macros, such as code expanded
1038/// by `derive` macros or deeply nested `async` code. Raising the limit is safe, but very
1039/// large values can make the compiler use more time and memory, and deeply nested code can
1040/// still overflow the compiler's own stack. Increase the limit in measured steps rather
1041/// than jumping to a very large number. If the limit is reached without an obvious cause,
1042/// the code may be more deeply recursive than intended.
1043///
1044/// For more information, see the Reference on [the `recursion_limit` attribute].
1045///
1046/// [the `recursion_limit` attribute]: ../reference/attributes/limits.html#the-recursion_limit-attribute
1047const _: () = ();