diff --git a/src/attributes.md b/src/attributes.md index f3ca9173e..399a8852a 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -1,6 +1,7 @@ {{#include attributes-redirect.html}} # Attributes +r[attributes.syntax] > **Syntax**\ > _InnerAttribute_ :\ >    `#` `!` `[` _Attr_ `]` @@ -16,20 +17,24 @@ >       [_DelimTokenTree_]\ >    | `=` [_Expression_] +r[attributes.intro] An _attribute_ is a general, free-form metadatum that is interpreted according to name, convention, language, and compiler version. Attributes are modeled on Attributes in [ECMA-335], with the syntax coming from [ECMA-334] \(C#). +r[attributes.inner] _Inner attributes_, written with a bang (`!`) after the hash (`#`), apply to the item that the attribute is declared within. _Outer attributes_, written without the bang after the hash, apply to the thing that follows the attribute. +r[attributes.input] The attribute consists of a path to the attribute, followed by an optional delimited token tree whose interpretation is defined by the attribute. Attributes other than macro attributes also allow the input to be an equals sign (`=`) followed by an expression. See the [meta item syntax](#meta-item-attribute-syntax) below for more details. +r[attributes.safety] An attribute may be unsafe to apply. To avoid undefined behavior when using these attributes, certain obligations that cannot be checked by the compiler must be met. To assert these have been, the attribute is wrapped in @@ -41,6 +46,7 @@ The following attributes are unsafe: * [`link_section`] * [`no_mangle`] +r[attributes.kind] Attributes can be classified into the following kinds: * [Built-in attributes] @@ -48,6 +54,7 @@ Attributes can be classified into the following kinds: * [Derive macro helper attributes] * [Tool attributes](#tool-attributes) +r[attributes.allowed-position] Attributes may be applied to many things in the language: * All [item declarations] accept outer attributes while [external blocks], @@ -100,9 +107,13 @@ fn some_unused_variables() { ## Meta Item Attribute Syntax +r[attributes.meta] + +r[attributes.meta.intro] A "meta item" is the syntax used for the _Attr_ rule by most [built-in attributes]. It has the following grammar: +r[attributes.meta.syntax] > **Syntax**\ > _MetaItem_ :\ >       [_SimplePath_]\ @@ -116,10 +127,12 @@ attributes]. It has the following grammar: >       _MetaItem_\ >    | [_Expression_] +r[attributes.meta.literal-expr] Expressions in meta items must macro-expand to literal expressions, which must not include integer or float type suffixes. Expressions which are not literal expressions will be syntactically accepted (and can be passed to proc-macros), but will be rejected after parsing. +r[attributes.meta.order] Note that if the attribute appears within another macro, it will be expanded after that outer macro. For example, the following code will expand the `Serialize` proc-macro first, which must preserve the `include_str!` call in @@ -133,6 +146,7 @@ struct Foo { } ``` +r[attributes.meta.order-macro] Additionally, macros in attributes will be expanded only after all other attributes applied to the item: ```rust ignore @@ -143,6 +157,7 @@ Additionally, macros in attributes will be expanded only after all other attribu fn foo() {} ``` +r[attributes.meta.builtin] Various built-in attributes use different subsets of the meta item syntax to specify their inputs. The following grammar rules show some commonly used forms: @@ -175,6 +190,9 @@ _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` ## Active and inert attributes +r[attributes.activity] + +r[attributes.activity.intro] An attribute is either active or inert. During attribute processing, *active attributes* remove themselves from the thing they are on while *inert attributes* stay on. @@ -185,15 +203,20 @@ active. All other attributes are inert. ## Tool attributes +r[attributes.tool] + +r[attributes.tool.intro] The compiler may allow attributes for external tools where each tool resides in its own module in the [tool prelude]. The first segment of the attribute path is the name of the tool, with one or more additional segments whose interpretation is up to the tool. +r[attributes.tool.ignored] When a tool is not in use, the tool's attributes are accepted without a warning. When the tool is in use, the tool is responsible for processing and interpretation of its attributes. +r[attributes.tool.prelude] Tool attributes are not available if the [`no_implicit_prelude`] attribute is used. @@ -213,19 +236,24 @@ pub fn f() {} ## Built-in attributes index +r[attributes.builtin] + The following is an index of all built-in attributes. - Conditional compilation - [`cfg`] --- Controls conditional compilation. - [`cfg_attr`] --- Conditionally includes attributes. + - Testing - [`test`] --- Marks a function as a test. - [`ignore`] --- Disables a test function. - [`should_panic`] --- Indicates a test should generate a panic. + - Derive - [`derive`] --- Automatic trait implementations. - [`automatically_derived`] --- Marker for implementations created by `derive`. + - Macros - [`macro_export`] --- Exports a `macro_rules` macro for cross-crate usage. - [`macro_use`] --- Expands macro visibility, or imports macros from other @@ -233,12 +261,14 @@ The following is an index of all built-in attributes. - [`proc_macro`] --- Defines a function-like macro. - [`proc_macro_derive`] --- Defines a derive macro. - [`proc_macro_attribute`] --- Defines an attribute macro. + - Diagnostics - [`allow`], [`expect`], [`warn`], [`deny`], [`forbid`] --- Alters the default lint level. - [`deprecated`] --- Generates deprecation notices. - [`must_use`] --- Generates a lint for unused values. - [`diagnostic::on_unimplemented`] --- Hints the compiler to emit a certain error message if a trait is not implemented. + - ABI, linking, symbols, and FFI - [`link`] --- Specifies a native library to link with an `extern` block. - [`link_name`] --- Specifies the name of the symbol for functions or statics @@ -257,6 +287,7 @@ The following is an index of all built-in attributes. - [`used`] --- Forces the compiler to keep a static item in the output object file. - [`crate_name`] --- Specifies the crate name. + - Code generation - [`inline`] --- Hint to inline code. - [`cold`] --- Hint that a function is unlikely to be called. @@ -264,28 +295,36 @@ The following is an index of all built-in attributes. - [`target_feature`] --- Configure platform-specific code generation. - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`. - [`instruction_set`] - Specify the instruction set used to generate a functions code + - Documentation - `doc` --- Specifies documentation. See [The Rustdoc Book] for more information. [Doc comments] are transformed into `doc` attributes. + - Preludes - [`no_std`] --- Removes std from the prelude. - [`no_implicit_prelude`] --- Disables prelude lookups within a module. + - Modules - [`path`] --- Specifies the filename for a module. + - Limits - [`recursion_limit`] --- Sets the maximum recursion limit for certain compile-time operations. - [`type_length_limit`] --- Sets the maximum size of a polymorphic type. + - Runtime - [`panic_handler`] --- Sets the function to handle panics. - [`global_allocator`] --- Sets the global memory allocator. - [`windows_subsystem`] --- Specifies the windows subsystem to link with. + - Features - `feature` --- Used to enable unstable or experimental compiler features. See [The Unstable Book] for features implemented in `rustc`. + - Type System - [`non_exhaustive`] --- Indicate that a type will have more fields/variants added in future. + - Debugger - [`debugger_visualizer`] --- Embeds a file that specifies debugger output for a type. - [`collapse_debuginfo`] --- Controls how macro invocations are encoded in debuginfo. diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index f30c296bc..3e24a3297 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -1,13 +1,19 @@ # Code generation attributes +r[attributes.codegen] + The following [attributes] are used for controlling code generation. ## Optimization hints +r[attributes.codegen.hint] + +r[attributes.codegen.hint.cold-inline] The `cold` and `inline` [attributes] give suggestions to generate code in a way that may be faster than what it would do without the hint. The attributes are only hints, and may be ignored. +r[attributes.codegen.hint.usage] Both attributes can be used on [functions]. When applied to a function in a [trait], they apply only to that function when used as a default function for a trait implementation and not to all trait implementations. The attributes @@ -15,6 +21,9 @@ have no effect on a trait function without a body. ### The `inline` attribute +r[attributes.codegen.inline] + +r[attributes.codegen.inline.intro] The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined. @@ -23,6 +32,7 @@ function where it is defined. > internal heuristics. Incorrectly inlining functions can make the program > slower, so this attribute should be used with care. +r[attributes.codegen.inline.modes] There are three ways to use the inline attribute: * `#[inline]` *suggests* performing an inline expansion. @@ -36,17 +46,24 @@ There are three ways to use the inline attribute: ### The `cold` attribute +r[attributes.codegen.cold] + The *`cold` [attribute]* suggests that the attributed function is unlikely to be called. ## The `no_builtins` attribute +r[attributes.codegen.no_builtins] + The *`no_builtins` [attribute]* may be applied at the crate level to disable optimizing certain code patterns to invocations of library functions that are assumed to exist. ## The `target_feature` attribute +r[attributes.codegen.target_feature] + +r[attributes.codegen.target_feature.intro] The *`target_feature` [attribute]* may be applied to a function to enable code generation of that function for specific platform architecture features. It uses the [_MetaListNameValueStr_] syntax with a single key of @@ -58,24 +75,31 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of unsafe fn foo_avx2() {} ``` +r[attributes.codegen.target_feature.arch] Each [target architecture] has a set of features that may be enabled. It is an error to specify a feature for a target architecture that the crate is not being compiled for. +r[attributes.codegen.target_feature.target-ub] It is [undefined behavior] to call a function that is compiled with a feature that is not supported on the current platform the code is running on, *except* if the platform explicitly documents this to be safe. +r[attributes.codegen.target_feature.inline] Functions marked with `target_feature` are not inlined into a context that does not support the given features. The `#[inline(always)]` attribute may not be used with a `target_feature` attribute. ### Available features +r[attributes.codegen.target_feature.availability] + The following is a list of the available feature names. #### `x86` or `x86_64` +r[attributes.codegen.target_feature.x86] + Executing code with unsupported features is undefined behavior on this platform. Hence this platform requires that `#[target_feature]` is only applied to [`unsafe` functions][unsafe function]. @@ -143,6 +167,8 @@ Feature | Implicitly Enables | Description #### `aarch64` +r[attributes.codegen.target_feature.aarch64] + This platform requires that `#[target_feature]` is only applied to [`unsafe` functions][unsafe function]. @@ -206,6 +232,8 @@ Feature | Implicitly Enables | Feature Name #### `riscv32` or `riscv64` +r[attributes.codegen.target_feature.riscv] + This platform requires that `#[target_feature]` is only applied to [`unsafe` functions][unsafe function]. @@ -266,6 +294,8 @@ Feature | Implicitly Enables | Description #### `wasm32` or `wasm64` +r[attributes.codegen.target_feature.wasm] + `#[target_feature]` may be used with both safe and [`unsafe` functions][unsafe function] on Wasm platforms. It is impossible to cause undefined behavior via the `#[target_feature]` attribute because @@ -293,11 +323,15 @@ Feature | Implicitly Enables | Description ### Additional information +r[attributes.codegen.target_feature.info] + +r[attributes.codegen.target_feature.remark-cfg] See the [`target_feature` conditional compilation option] for selectively enabling or disabling compilation of code based on compile-time settings. Note that this option is not affected by the `target_feature` attribute, and is only driven by the features enabled for the entire crate. +r[attributes.codegen.target_feature.remark-rt] See the [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`] macros in the standard library for runtime feature detection on these platforms. @@ -308,11 +342,17 @@ in the standard library for runtime feature detection on these platforms. ## The `track_caller` attribute +r[attributes.codegen.track_caller] + +r[attributes.codegen.track_caller.allowed-positions] The `track_caller` attribute may be applied to any function with [`"Rust"` ABI][rust-abi] -with the exception of the entry point `fn main`. When applied to functions and methods in -trait declarations, the attribute applies to all implementations. If the trait provides a +with the exception of the entry point `fn main`. + +r[attributes.codegen.track_caller.traits] +When applied to functions and methods in trait declarations, the attribute applies to all implementations. If the trait provides a default implementation with the attribute, then the attribute also applies to override implementations. +r[attributes.codegen.track_caller.extern] When applied to a function in an `extern` block the attribute must also be applied to any linked implementations, otherwise undefined behavior results. When applied to a function which is made available to an `extern` block, the declaration in the `extern` block must also have the attribute, @@ -320,6 +360,7 @@ otherwise undefined behavior results. ### Behavior +r[attributes.codegen.track_caller.behavior] Applying the attribute to a function `f` allows code within `f` to get a hint of the [`Location`] of the "topmost" tracked call that led to `f`'s invocation. At the point of observation, an implementation behaves as if it walks up the stack from `f`'s frame to find the nearest frame of an @@ -399,8 +440,12 @@ And so on. ### Limitations +r[attributes.codegen.track_caller.limits] + +r[attributes.codegen.track_caller.hint] This information is a hint and implementations are not required to preserve it. +r[attributes.codegen.track_caller.decay] In particular, coercing a function with `#[track_caller]` to a function pointer creates a shim which appears to observers to have been called at the attributed function's definition site, losing actual caller information across virtual calls. A common example of this coercion is the creation of a @@ -431,18 +476,27 @@ trait object whose methods are attributed. ## The `instruction_set` attribute +r[attributes.codegen.instruction_set] + +r[attributes.codegen.instruction_set.allowed-positions] The *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for. + +r[attributes.codegen.instruction_set.behavior] This allows mixing more than one instruction set in a single program on CPU architectures that support it. + +r[attributes.codegen.instruction_set.syntax] It uses the [_MetaListPath_] syntax, and a path comprised of the architecture family name and instruction set name. [_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax +r[attributes.codegen.instruction_set.target-limits] It is a compilation error to use the `instruction_set` attribute on a target that does not support it. ### On ARM -For the `ARMv4T` and `ARMv5te` architectures, the following are supported: +r[attributes.codegen.instruction_set.arm] +For the `ARMv4T` and `ARMv5te` architectures, the following are supported: * `arm::a32` --- Generate the function as A32 "ARM" code. * `arm::t32` --- Generate the function as T32 "Thumb" code. diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 21add01ca..2521c4e83 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -1,20 +1,32 @@ # Debugger attributes +r[attributes.debugger] + The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or WinDbg. ## The `debugger_visualizer` attribute +r[attributes.debugger.debugger_visualizer] + +r[attributes.debugger.debugger_visualizer.intro] The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information. This enables an improved debugger experience for displaying values in the debugger. + +r[attributes.debugger.debugger_visualizer.syntax] It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute. ### Using `debugger_visualizer` with Natvis +r[attributes.debugger.debugger_visualizer.natvis] + +r[attributes.debugger.debugger_visualizer.natvis.intro] Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types. For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation]. +r[attributes.debugger.debugger_visualizer.natvis.msvc] This attribute only supports embedding Natvis files on `-windows-msvc` targets. +r[attributes.debugger.debugger_visualizer.natvis.path] The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file: @@ -72,6 +84,9 @@ When viewed under WinDbg, the `fancy_rect` variable would be shown as follows: ### Using `debugger_visualizer` with GDB +r[attributes.debugger.debugger_visualizer.gdb] + +r[attributes.debugger.debugger_visualizer.gdb.pretty] GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view. For detailed information on pretty printers, refer to GDB's [pretty printing documentation]. @@ -81,6 +96,7 @@ There are two ways to enable auto-loading embedded pretty printers: For more information, see GDB's [auto-loading documentation]. 1. Create a file named `gdbinit` under `$HOME/.config/gdb` (you may need to create the directory if it doesn't already exist). Add the following line to that file: `add-auto-load-safe-path path/to/binary`. +r[attributes.debugger.debugger_visualizer.gdb.path] These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file. @@ -142,16 +158,22 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil ## The `collapse_debuginfo` attribute +r[attributes.debugger.collapse_debuginfo] + +r[attributes.debugger.collapse_debuginfo.intro] The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site, when generating debuginfo for code calling this macro. +r[attributes.debugger.collapse_debuginfo.syntax] The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to macro definitions. +r[attributes.debugger.collapse_debuginfo.options] Accepted options: - `#[collapse_debuginfo(yes)]` --- code locations in debuginfo are collapsed. - `#[collapse_debuginfo(no)]` --- code locations in debuginfo are not collapsed. - `#[collapse_debuginfo(external)]` --- code locations in debuginfo are collapsed only if the macro comes from a different crate. +r[attributes.debugger.collapse_debuginfo.default] The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros. For built-in macros the default is `yes`. diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 44ce8c7b3..6a61dbf78 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -1,7 +1,13 @@ # Derive +r[attributes.derive] + +r[attributes.derive.intro] The *`derive` attribute* allows new [items] to be automatically generated for -data structures. It uses the [_MetaListPaths_] syntax to specify a list of +data structures. + +r[attributes.derive.syntax] +It uses the [_MetaListPaths_] syntax to specify a list of traits to implement or paths to [derive macros] to process. For example, the following will create an [`impl` item] for the @@ -27,10 +33,12 @@ impl PartialEq for Foo { } ``` +r[attributes.derive.proc-macro] You can implement `derive` for your own traits through [procedural macros]. ## The `automatically_derived` attribute +r[attributes.derive.automatically_derived] The *`automatically_derived` attribute* is automatically added to [implementations] created by the `derive` attribute for built-in traits. It has no direct effect, but it may be used by tools and diagnostic lints to diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 6d21a5adf..eb5caf2e6 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -1,25 +1,41 @@ # Diagnostic attributes +r[attributes.diagnostics] + The following [attributes] are used for controlling or generating diagnostic messages during compilation. ## Lint check attributes +r[attributes.diagnostics.lint] + A lint check names a potentially undesirable coding pattern, such as -unreachable code or omitted documentation. The lint attributes `allow`, +unreachable code or omitted documentation. + +r[attributes.diagnostics.lint.level] +The lint attributes `allow`, `expect`, `warn`, `deny`, and `forbid` use the [_MetaListPaths_] syntax to specify a list of lint names to change the lint level for the entity to which the attribute applies. For any lint check `C`: +r[attributes.diagnostics.lint.allow] * `#[allow(C)]` overrides the check for `C` so that violations will go unreported. + +r[attributes.diagnostics.lint.expect] * `#[expect(C)]` indicates that lint `C` is expected to be emitted. The attribute will suppress the emission of `C` or issue a warning, if the expectation is unfulfilled. + +r[attributes.diagnostics.lint.warn] * `#[warn(C)]` warns about violations of `C` but continues compilation. + +r[attributes.diagnostics.lint.deny] * `#[deny(C)]` signals an error after encountering a violation of `C`, + +r[attributes.diagnostics.lint.forbid] * `#[forbid(C)]` is the same as `deny(C)`, but also forbids changing the lint level afterwards, @@ -42,6 +58,7 @@ pub mod m1 { } ``` +r[attributes.diagnostics.lint.override] Lint attributes can override the level specified from a previous attribute, as long as the level does not attempt to change a forbidden lint (except for `deny`, which is allowed inside a `forbid` context, but ignored). @@ -89,6 +106,7 @@ pub mod m3 { ### Lint Reasons +r[attributes.diagnostics.lint.reason] All lint attributes support an additional `reason` parameter, to give context why a certain attribute was added. This reason will be displayed as part of the lint message if the lint is emitted at the defined level. @@ -125,6 +143,9 @@ pub fn get_path() -> PathBuf { ### The `#[expect]` attribute +r[attributes.diagnostics.expect] + +r[attributes.diagnostics.expect.intro] The `#[expect(C)]` attribute creates a lint expectation for lint `C`. The expectation will be fulfilled, if a `#[warn(C)]` attribute at the same location would result in a lint emission. If the expectation is unfulfilled, because @@ -150,6 +171,7 @@ fn main() { } ``` +r[attributes.diagnostics.expect.fulfillment] The lint expectation is only fulfilled by lint emissions which have been suppressed by the `expect` attribute. If the lint level is modified in the scope with other level attributes like `allow` or `warn`, the lint emission will be handled accordingly and the @@ -179,6 +201,7 @@ fn select_song() { } ``` +r[attributes.diagnostics.expect.independent] If the `expect` attribute contains several lints, each one is expected separately. For a lint group it's enough if one lint inside the group has been emitted: @@ -207,6 +230,7 @@ pub fn another_example() { ### Lint groups +r[attributes.diagnostics.lint.group] Lints may be organized into named groups so that the level of related lints can be adjusted together. Using a named group is equivalent to listing out the lints within that group. @@ -227,6 +251,7 @@ fn example() { } ``` +r[attributes.diagnostics.lint.group.warnings] There is a special group named "warnings" which includes all lints at the "warn" level. The "warnings" group ignores attribute order and applies to all lints that would otherwise warn within the entity. @@ -246,9 +271,13 @@ fn example_err() { ### Tool lint attributes +r[attributes.diagnostics.lint.tool] + +r[attributes.diagnostics.lint.tool.intro] Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of certain tools. +r[attributes.diagnostics.lint.tool.activation] Tool lints only get checked when the associated tool is active. If a lint attribute, such as `allow`, references a nonexistent tool lint, the compiler will not warn about the nonexistent lint until you use the tool. @@ -276,10 +305,14 @@ fn foo() { ## The `deprecated` attribute +r[attributes.diagnostics.deprecated] + +r[attributes.diagnostics.deprecated.intro] The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue warnings on usage of `#[deprecated]` items. `rustdoc` will show item deprecation, including the `since` version and `note`, if available. +r[attributes.diagnostics.deprecated.syntax] The `deprecated` attribute has several forms: - `deprecated` --- Issues a generic message. @@ -293,6 +326,7 @@ The `deprecated` attribute has several forms: message. This is typically used to provide an explanation about the deprecation and preferred alternatives. +r[attributes.diagnostic.deprecated.allowed-positions] The `deprecated` attribute may be applied to any [item], [trait item], [enum variant], [struct field], [external block item], or [macro definition]. It cannot be applied to [trait implementation items]. When applied to an item @@ -318,15 +352,23 @@ The [RFC][1270-deprecation.md] contains motivations and more details. ## The `must_use` attribute +r[attributes.diagnostics.must_use] + +r[attributes.diagnostics.must_use.intro] The *`must_use` attribute* is used to issue a diagnostic warning when a value -is not "used". It can be applied to user-defined composite types +is not "used". + +r[attributes.diagnostics.must_use.allowed-positions] +The `must_use` attribute can be applied to user-defined composite types ([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions], and [traits]. +r[attributes.diagnostics.must_use.message] The `must_use` attribute may include a message by using the [_MetaNameValueStr_] syntax such as `#[must_use = "example message"]`. The message will be given alongside the warning. +r[attributes.diagnostics.must_use.type] When used on user-defined composite types, if the [expression] of an [expression statement] has that type, then the `unused_must_use` lint is violated. @@ -345,6 +387,7 @@ struct MustUse { MustUse::new(); ``` +r[attributes.diagnostics.must_use.fn] When used on a function, if the [expression] of an [expression statement] is a [call expression] to that function, then the `unused_must_use` lint is violated. @@ -357,6 +400,7 @@ fn five() -> i32 { 5i32 } five(); ``` +r[attributes.diagnostics.must_use.trait] When used on a [trait declaration], a [call expression] of an [expression statement] to a function that returns an [impl trait] or a [dyn trait] of that trait violates the `unused_must_use` lint. @@ -374,6 +418,7 @@ fn get_critical() -> impl Critical { get_critical(); ``` +r[attributes.diagnostics.must_use.trait-function] When used on a function in a trait declaration, then the behavior also applies when the call expression is a function from an implementation of the trait. @@ -391,6 +436,7 @@ impl Trait for i32 { 5i32.use_me(); ``` +r[attributes.diagnostics.must_use.trait-impl-function] When used on a function in a trait implementation, the attribute does nothing. > Note: Trivial no-op expressions containing the value will not violate the @@ -425,36 +471,58 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace +r[attributes.diagnostic.namespace] + +r[attributes.diagnostic.namespace.intro] The `#[diagnostic]` attribute namespace is a home for attributes to influence compile-time error messages. The hints provided by these attributes are not guaranteed to be used. + +r[attributes.diagnostic.namespace.unknown-invalid-syntax] Unknown attributes in this namespace are accepted, though they may emit warnings for unused attributes. Additionally, invalid inputs to known attributes will typically be a warning (see the attribute definitions for details). This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working. ### The `diagnostic::on_unimplemented` attribute +r[attributes.diagnostic.on_unimplemented] + +r[attributes.diagnostic.on_unimplemented.intro] The `#[diagnostic::on_unimplemented]` attribute is a hint to the compiler to supplement the error message that would normally be generated in scenarios where a trait is required but not implemented on a type. + +r[attributes.diagnostic.on_unimplemented.allowed-positions] The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. + +r[attributes.diagnostic.on_unimplemented.syntax] The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. -The following keys have the given meaning: +r[attributes.diagnostic.on_unimplemented.keys] +The following keys have the given meaning: * `message` --- The text for the top level error message. * `label` --- The text for the label shown inline in the broken code in the error message. * `note` --- Provides additional notes. +r[attributes.diagnostic.on_unimplemented.note-repetition] The `note` option can appear several times, which results in several note messages being emitted. + +r[attributes.diagnostic.on_unimplemented.repetition] If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. + +r[attributes.diagnostic.on_unimplemented.warnings] Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. +r[attributes.diagnostic.on_unimplemented.format-string] All three options accept a string as an argument, interpreted using the same formatting as a [`std::fmt`] string. -Format parameters with the given named parameter will be replaced with the following text: +r[attributes.diagnostic.on_unimplemented.format-parameters] +Format parameters with the given named parameter will be replaced with the following text: * `{Self}` --- The name of the type implementing the trait. * `{` *GenericParameterName* `}` --- The name of the generic argument's type for the given generic parameter. +r[attributes.diagnostic.on_unimplemented.invalid-formats] Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +r[attributes.diagnostic.on_unimplemented.invalid-string] Invalid format strings may generate a warning, but are otherwise allowed, but may not display as intended. Format specifiers may generate a warning, but are otherwise ignored. diff --git a/src/attributes/limits.md b/src/attributes/limits.md index 79f292a31..1c8c46bb5 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -1,12 +1,20 @@ # Limits +r[attributes.limits] + The following [attributes] affect compile-time limits. ## The `recursion_limit` attribute +r[attributes.limits.recursion_limit] + +r[attributes.limits.recursion_limit.intro] The *`recursion_limit` attribute* may be applied at the [crate] level to set the maximum depth for potentially infinitely-recursive compile-time operations -like macro expansion or auto-dereference. It uses the [_MetaNameValueStr_] +like macro expansion or auto-dereference. + +r[attributes.limits.recursion_limit.syntax] +It uses the [_MetaNameValueStr_] syntax to specify the recursion depth. > Note: The default in `rustc` is 128. @@ -35,12 +43,17 @@ a!{} ## The `type_length_limit` attribute +r[attributes.limits.type_length_limit] + > **Note**: This limit is only enforced when the nightly `-Zenforce-type-length-limit` flag is active. > > For more information, see . +r[attributes.limits.type_length_limit.intro] The *`type_length_limit` attribute* limits the maximum number of type substitutions made when constructing a concrete type during monomorphization. + +r[attributes.limits.type_length_limit.syntax] It is applied at the [crate] level, and uses the [_MetaNameValueStr_] syntax to set the limit based on the number of type substitutions. diff --git a/src/attributes/testing.md b/src/attributes/testing.md index a2db083a7..d245da66b 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -1,5 +1,7 @@ # Testing attributes +r[attributes.testing] + The following [attributes] are used for specifying functions for performing tests. Compiling a crate in "test" mode enables building the test functions along with a test harness for executing the tests. Enabling the test mode also @@ -7,9 +9,16 @@ enables the [`test` conditional compilation option]. ## The `test` attribute -The *`test` attribute* marks a function to be executed as a test. These -functions are only compiled when in test mode. Test functions must be free, -monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: +r[attributes.testing.test] + +r[attributes.testing.test.intro] +The *`test` attribute* marks a function to be executed as a test. + +r[attributes.testing.test.enabled] +These functions are only compiled when in test mode. + +r[attributes.testing.test.allowed-positions] +Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: * `()` * `Result where T: Termination, E: Debug` @@ -21,6 +30,7 @@ monomorphic functions that take no arguments, and the return type must implement > Note: The test mode is enabled by passing the `--test` argument to `rustc` > or using `cargo test`. +r[attributes.testing.test.success] The test harness calls the returned value's [`report`] method, and classifies the test as passed or failed depending on whether the resulting [`ExitCode`] represents successful termination. In particular: * Tests that return `()` pass as long as they terminate and do not panic. @@ -42,10 +52,14 @@ fn test_the_thing() -> io::Result<()> { ## The `ignore` attribute +r[attributes.testing.ignore] + +r[attributes.testing.ignore.intro] A function annotated with the `test` attribute can also be annotated with the `ignore` attribute. The *`ignore` attribute* tells the test harness to not execute that function as a test. It will still be compiled when in test mode. +r[attributes.testing.ignore.syntax] The `ignore` attribute may optionally be written with the [_MetaNameValueStr_] syntax to specify a reason why the test is ignored. @@ -62,10 +76,17 @@ fn mytest() { ## The `should_panic` attribute +r[attributes.testing.should_panic] + +r[attributes.testing.should_panic.intro] A function annotated with the `test` attribute that returns `()` can also be -annotated with the `should_panic` attribute. The *`should_panic` attribute* +annotated with the `should_panic` attribute. + +r[attributes.testing.should_panic.behavior] +The *`should_panic` attribute* makes the test only pass if it actually panics. +r[attributes.testing.should_panic.syntax] The `should_panic` attribute may optionally take an input string that must appear within the panic message. If the string is not found in the message, then the test will fail. The string may be passed using the diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index d3ea63233..e26de1210 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -1,16 +1,25 @@ # Type system attributes +r[attributes.type-system] + The following [attributes] are used for changing how a type can be used. ## The `non_exhaustive` attribute +r[attributes.type-system.non_exhaustive] + +r[attributes.type-system.non_exhaustive.intro] The *`non_exhaustive` attribute* indicates that a type or variant may have -more fields or variants added in the future. It can be applied to -[`struct`s][struct], [`enum`s][enum], and `enum` variants. +more fields or variants added in the future. + +r[attributes.type-system.non_exhaustive.allowed-positions] +It can be applied to [`struct`s][struct], [`enum`s][enum], and `enum` variants. +r[attributes.type-system.non_exhaustive.syntax] The `non_exhaustive` attribute uses the [_MetaWord_] syntax and thus does not take any inputs. +r[attributes.type-system.non_exhaustive.same-crate] Within the defining crate, `non_exhaustive` has no effect. ```rust @@ -65,9 +74,11 @@ match message { } ``` +r[attributes.type-system.non_exhaustive.external-crate] Outside of the defining crate, types annotated with `non_exhaustive` have limitations that preserve backwards compatibility when new fields or variants are added. +r[attributes.type-system.non_exhaustive.construction] Non-exhaustive types cannot be constructed outside of the defining crate: - Non-exhaustive variants ([`struct`][struct] or [`enum` variant][enum]) cannot be constructed @@ -119,6 +130,7 @@ let message = Message::Reaction(0); let message = Message::Quit; ``` +r[attributes.type-system.non_exhaustive.match] There are limitations when matching on non-exhaustive types outside of the defining crate: - When pattern matching on a non-exhaustive variant ([`struct`][struct] or [`enum` variant][enum]),