From 173a829f57801ab1b012192c8fe5749bdaa5999b Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 12:14:52 -0400 Subject: [PATCH 01/18] Add identifier syntax to attributes.md --- src/attributes.md | 60 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index f3ca9173e..794f8750f 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -1,6 +1,10 @@ {{#include attributes-redirect.html}} # Attributes +r[attributes] + + +r[attributes.syntax] > **Syntax**\ > _InnerAttribute_ :\ >    `#` `!` `[` _Attr_ `]` @@ -16,20 +20,24 @@ >       [_DelimTokenTree_]\ >    | `=` [_Expression_] +r[attributes.general] 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,15 +49,15 @@ The following attributes are unsafe: * [`link_section`] * [`no_mangle`] +r[attributes.kind] Attributes can be classified into the following kinds: - * [Built-in attributes] * [Macro attributes][attribute macros] * [Derive macro helper attributes] * [Tool attributes](#tool-attributes) +r[attributes.application] Attributes may be applied to many things in the language: - * All [item declarations] accept outer attributes while [external blocks], [functions], [implementations], and [modules] accept inner attributes. * Most [statements] accept outer attributes (see [Expression Attributes] for @@ -100,9 +108,14 @@ fn some_unused_variables() { ## Meta Item Attribute Syntax +r[attributes.meta] + + +r[attributes.meta.general] 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 +129,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 +148,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 +159,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 +192,9 @@ _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` ## Active and inert attributes +r[attributes.activity] + +r[attributes.activity.general] 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 +205,20 @@ active. All other attributes are inert. ## Tool attributes +r[attributes.tool] + +r[attributes.tool.general] 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 +238,28 @@ pub fn f() {} ## Built-in attributes index +r[attributes.builtin] + The following is an index of all built-in attributes. +r[attributes.builtin.cfg] - Conditional compilation - [`cfg`] --- Controls conditional compilation. - [`cfg_attr`] --- Conditionally includes attributes. + +r[attributes.builtin.testing] - Testing - [`test`] --- Marks a function as a test. - [`ignore`] --- Disables a test function. - [`should_panic`] --- Indicates a test should generate a panic. + +r[attributes.builtin.derive] - Derive - [`derive`] --- Automatic trait implementations. - [`automatically_derived`] --- Marker for implementations created by `derive`. + +r[attributes.builtin.macros] - Macros - [`macro_export`] --- Exports a `macro_rules` macro for cross-crate usage. - [`macro_use`] --- Expands macro visibility, or imports macros from other @@ -233,12 +267,16 @@ 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. + +r[attributes.builtin.diagnostic] - 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. + +r[attributes.builtin.linkage] - 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 +295,8 @@ 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. + +r[attributes.builtin.codegen] - Code generation - [`inline`] --- Hint to inline code. - [`cold`] --- Hint that a function is unlikely to be called. @@ -264,28 +304,44 @@ 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 + +r[attributes.builtin.doc] - Documentation - `doc` --- Specifies documentation. See [The Rustdoc Book] for more information. [Doc comments] are transformed into `doc` attributes. + +r[attributes.builtin.prelude] - Preludes - [`no_std`] --- Removes std from the prelude. - [`no_implicit_prelude`] --- Disables prelude lookups within a module. + +r[attributes.builtin.module] - Modules - [`path`] --- Specifies the filename for a module. + +r[attributes.builtin.limits] - Limits - [`recursion_limit`] --- Sets the maximum recursion limit for certain compile-time operations. - [`type_length_limit`] --- Sets the maximum size of a polymorphic type. + +r[attributes.builtin.rt] - 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. + +r[attributes.builtin.unstable] - Features - `feature` --- Used to enable unstable or experimental compiler features. See [The Unstable Book] for features implemented in `rustc`. + +r[attributes.builtin.typesystem] - Type System - [`non_exhaustive`] --- Indicate that a type will have more fields/variants added in future. + +r[attributes.builtin.debugging] - Debugger - [`debugger_visualizer`] --- Embeds a file that specifies debugger output for a type. - [`collapse_debuginfo`] --- Controls how macro invocations are encoded in debuginfo. From e5acdc2cf8ba542d95e96aba7eadb8d61bb468d9 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 12:15:04 -0400 Subject: [PATCH 02/18] Add identifier syntax to attributes.codegen --- src/attributes/codegen.md | 61 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index f30c296bc..0e170cea9 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.codgen.inline] + +r[attributes.codegen.inline.general] 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,25 @@ There are three ways to use the inline attribute: ### The `cold` attribute +r[attribute.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.general] 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 +76,31 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of unsafe fn foo_avx2() {} ``` +r[attributes.codegen.target_features.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_features.precondition] 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_features.restriction] 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_features.availability] + The following is a list of the available feature names. #### `x86` or `x86_64` +r[attributes.codegen.target_features.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 +168,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 +233,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 +295,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 +324,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 +343,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.restriction] 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 +361,7 @@ otherwise undefined behavior results. ### Behavior +r[attributes.codegen.track_caller.behaviour] 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 +441,12 @@ And so on. ### Limitations +r[attributes.codegen.track_caller.limits] + +r[attributes.codegent.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 +477,27 @@ trait object whose methods are attributed. ## The `instruction_set` attribute +r[attributes.codegen.instruction_set] + +r[attributes.codegen.instruction_set.restriction] 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.behaviour] 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. From 41fe2114b59659e3a55a9cead98871eca5b990a3 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 12:15:15 -0400 Subject: [PATCH 03/18] Add identifier syntax to attributes.debugger --- src/attributes/debugger.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 21add01ca..44e05e81d 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.general] 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.restriction] 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-general] 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-restrictions] 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,10 @@ 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 +97,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 +159,23 @@ 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.general] 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`. From 3b6ebe1d694bc88cca02d3b2b55d8812639b1158 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 12:16:29 -0400 Subject: [PATCH 04/18] Add identifier syntax to attributes.derive --- src/attributes/derive.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 44ce8c7b3..c8938f3a9 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -1,7 +1,14 @@ # Derive +r[attributes.derive] + + +r[attributes.derived.general] 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 +34,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 From 42fbf9b48cc74702038369904e4a7a264b0c51f8 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 12:30:17 -0400 Subject: [PATCH 05/18] Add identifier syntax to attributes.diagnostics --- src/attributes/diagnostics.md | 72 +++++++++++++++++++++++++++++++++-- 1 file changed, 69 insertions(+), 3 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 6d21a5adf..d1dde2e04 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.lints] + 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.lints.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.lints.allow] * `#[allow(C)]` overrides the check for `C` so that violations will go unreported. + +r[attributes.diagnostics.lints.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.lints.warn] * `#[warn(C)]` warns about violations of `C` but continues compilation. + +r[attributes.diagnostics.lints.deny] * `#[deny(C)]` signals an error after encountering a violation of `C`, + +r[attributes.diagnostics.lints.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.lints.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.lints.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.general] 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.lints.expect.fulfilment] 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.lints.groups] 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.lints.warnings-group] 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.lints.tools] + +r[attributes.lints.tools.general] Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of certain tools. +r[attributes.lints.tools.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.general] 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.deprectead.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.diagnostics.deprecated.application] 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,20 @@ The [RFC][1270-deprecation.md] contains motivations and more details. ## The `must_use` attribute +r[attributes.diagnostics.must_use] + +r[attributes.diagnostics.must_use.application] 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 ([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions], and [traits]. +r[attributes.diagnostics.must_use.syntax] 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.types] 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 +384,7 @@ struct MustUse { MustUse::new(); ``` +r[attributes.diagnostics.must_use.function] 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 +397,7 @@ fn five() -> i32 { 5i32 } five(); ``` +r[attributes.diagnostics.must_use.traits] 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 +415,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 +433,7 @@ impl Trait for i32 { 5i32.use_me(); ``` +r[attributes.diagnostics.must_use.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 +468,59 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace +r[attributes.diagnostics.namespace] + +r[attributes.diagnostics.namespace.general] 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.diagnostics.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.diagnostics.on_unimplemented] + +r[attributes.diagnostics.on_unimplemented.general] 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.diagnostics.on_unimplemented.restriction] The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. + +r[attributes.diagnostics.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.diagnostics.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.diagnostics.on_unimplemented-note-repetition] The `note` option can appear several times, which results in several note messages being emitted. + +r[attributes.diagnostics.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.diagnostics.on_unimplemented.warnings] Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. +r[attributes.diagnostics.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.diagnostics.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.diagnostics.invalid-formats] Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +r[attributes.diagnostics.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. From 8f980cb66731b9cd7995949b5972f3fd1be5c35d Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 13:04:48 -0400 Subject: [PATCH 06/18] Add identifier syntax to attributes.limits --- src/attributes/limits.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/attributes/limits.md b/src/attributes/limits.md index 79f292a31..a8af23550 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_limits] + +r[attributes.limits.recursion_limits.application] 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_limits.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.general] 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.restriction] It is applied at the [crate] level, and uses the [_MetaNameValueStr_] syntax to set the limit based on the number of type substitutions. From 065765765c96354450d8ac9389c37d409ac542b6 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 13:09:10 -0400 Subject: [PATCH 07/18] Add identifier syntax to attributes.testing --- src/attributes/testing.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index a2db083a7..4a303d303 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,17 @@ 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.general] +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.restriction] +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 +31,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.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 +53,15 @@ fn test_the_thing() -> io::Result<()> { ## The `ignore` attribute +r[attributes.testing.ignore] + + +r[attributes.testing.ignore.general] 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 +78,17 @@ fn mytest() { ## The `should_panic` attribute +r[attributes.testing.should_panic] + +r[attributes.testing.should_panic.restriction] 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.behaviour] +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 From 2b5d973526277850103c49243a56aaa50b6f83fa Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 6 Aug 2024 13:12:52 -0400 Subject: [PATCH 08/18] Add identifier syntax to attributes.type_system --- src/attributes/type_system.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index d3ea63233..b2a677efe 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -1,16 +1,26 @@ # 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.general] 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.restriction] +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 +75,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 +131,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]), From 043c99f1f30b2576d435cc1d2a360f352f0032d4 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:06:25 -0400 Subject: [PATCH 09/18] Fix style in modified chapters --- src/attributes/codegen.md | 2 +- src/attributes/derive.md | 2 +- src/attributes/diagnostics.md | 2 +- src/attributes/limits.md | 2 +- src/attributes/testing.md | 6 +++--- src/attributes/type_system.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 0e170cea9..33fa0be34 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -347,7 +347,7 @@ r[attributes.codegen.track_caller] r[attributes.codegen.track_caller.restriction] The `track_caller` attribute may be applied to any function with [`"Rust"` ABI][rust-abi] -with the exception of the entry point `fn main`. +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 diff --git a/src/attributes/derive.md b/src/attributes/derive.md index c8938f3a9..03f9fc469 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -5,7 +5,7 @@ r[attributes.derive] r[attributes.derived.general] The *`derive` attribute* allows new [items] to be automatically generated for -data structures. +data structures. r[attributes.derive.syntax] It uses the [_MetaListPaths_] syntax to specify a list of diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index d1dde2e04..1cf259aaa 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -10,7 +10,7 @@ messages during compilation. r[attributes.diagnostics.lints] A lint check names a potentially undesirable coding pattern, such as -unreachable code or omitted documentation. +unreachable code or omitted documentation. r[attributes.diagnostics.lints.level] The lint attributes `allow`, diff --git a/src/attributes/limits.md b/src/attributes/limits.md index a8af23550..b02e9c56a 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -11,7 +11,7 @@ r[attributes.limits.recursion_limits] r[attributes.limits.recursion_limits.application] 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. +like macro expansion or auto-dereference. r[attributes.limits.recursion_limits.syntax] It uses the [_MetaNameValueStr_] diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 4a303d303..4d9706f60 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -13,10 +13,10 @@ r[attributes.testing.test] r[attributes.testing.test.general] -The *`test` attribute* marks a function to be executed as a test. +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. +These functions are only compiled when in test mode. r[attributes.testing.test.restriction] Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: @@ -82,7 +82,7 @@ r[attributes.testing.should_panic] r[attributes.testing.should_panic.restriction] A function annotated with the `test` attribute that returns `()` can also be -annotated with the `should_panic` attribute. +annotated with the `should_panic` attribute. r[attributes.testing.should_panic.behaviour] The *`should_panic` attribute* diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index b2a677efe..cccdba19f 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -11,7 +11,7 @@ r[attributes.type-system.non_exhaustive] r[attributes.type-system.non_exhaustive.general] The *`non_exhaustive` attribute* indicates that a type or variant may have -more fields or variants added in the future. +more fields or variants added in the future. r[attributes.type-system.non_exhaustive.restriction] It can be applied to [`struct`s][struct], [`enum`s][enum], and `enum` variants. From b1a26cc214eb1a72a1af5bb857e6ff44756e7b66 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 7 Aug 2024 22:09:10 -0400 Subject: [PATCH 10/18] Appease link-checker --- src/attributes.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 794f8750f..fb37ad5cb 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -1,9 +1,6 @@ {{#include attributes-redirect.html}} # Attributes -r[attributes] - - r[attributes.syntax] > **Syntax**\ > _InnerAttribute_ :\ From aa93e9480d5b12772a41ab44442e0e13a4c1da47 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 10 Sep 2024 17:48:13 +0000 Subject: [PATCH 11/18] Apply suggestions from PR review --- src/attributes.md | 8 +-- src/attributes/codegen.md | 14 +++--- src/attributes/debugger.md | 14 +++--- src/attributes/derive.md | 2 +- src/attributes/diagnostics.md | 92 +++++++++++++++++------------------ src/attributes/limits.md | 8 +-- src/attributes/testing.md | 4 +- src/attributes/type_system.md | 2 +- 8 files changed, 72 insertions(+), 72 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index fb37ad5cb..02588b270 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -17,7 +17,7 @@ r[attributes.syntax] >       [_DelimTokenTree_]\ >    | `=` [_Expression_] -r[attributes.general] +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#). @@ -108,7 +108,7 @@ fn some_unused_variables() { r[attributes.meta] -r[attributes.meta.general] +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: @@ -191,7 +191,7 @@ _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` r[attributes.activity] -r[attributes.activity.general] +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. @@ -204,7 +204,7 @@ active. All other attributes are inert. r[attributes.tool] -r[attributes.tool.general] +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 diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 33fa0be34..cb27e214d 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -23,7 +23,7 @@ have no effect on a trait function without a body. r[attributes.codgen.inline] -r[attributes.codegen.inline.general] +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. @@ -64,7 +64,7 @@ assumed to exist. r[attributes.codegen.target_feature] -r[attributes.codegen.target_feature.general] +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 @@ -76,17 +76,17 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of unsafe fn foo_avx2() {} ``` -r[attributes.codegen.target_features.arch] +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_features.precondition] +r[attributes.codegen.target_feature.precondition] 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_features.restriction] +r[attributes.codegen.target_feature.restriction-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. @@ -361,7 +361,7 @@ otherwise undefined behavior results. ### Behavior -r[attributes.codegen.track_caller.behaviour] +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 @@ -443,7 +443,7 @@ And so on. r[attributes.codegen.track_caller.limits] -r[attributes.codegent.track_caller.hint] +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] diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 44e05e81d..40074b5c7 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -8,7 +8,7 @@ The following [attributes] are used for enhancing the debugging experience when r[attributes.debugger.debugger_visualizer] -r[attributes.debugger.debugger_visualizer.general] +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. @@ -19,14 +19,14 @@ It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be s r[attributes.debugger.debugger_visualizer.natvis] -r[attributes.debugger.debugger_visualizer.natvis-general] +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-restrictions] +r[attributes.debugger.debugger_visualizer.natvis.restrictions] This attribute only supports embedding Natvis files on `-windows-msvc` targets. -r[attributes.debugger.debugger_visualizer.natvis-path] +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: @@ -87,7 +87,7 @@ When viewed under WinDbg, the `fancy_rect` variable would be shown as follows: r[attributes.debugger.debugger_visualizer.gdb] -r[attributes.debugger.debugger_visualizer.gdb-pretty] +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]. @@ -97,7 +97,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] +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. @@ -162,7 +162,7 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil r[attributes.debugger.collapse_debuginfo] -r[attributes.debugger.collapse_debuginfo.general] +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. diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 03f9fc469..07238c44e 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -3,7 +3,7 @@ r[attributes.derive] -r[attributes.derived.general] +r[attributes.derive.intro] The *`derive` attribute* allows new [items] to be automatically generated for data structures. diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 1cf259aaa..dbbf6ce00 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -1,18 +1,18 @@ # Diagnostic attributes -r[attributes.diagnostics] +r[attributes.diagnostic] The following [attributes] are used for controlling or generating diagnostic messages during compilation. ## Lint check attributes -r[attributes.diagnostics.lints] +r[attributes.diagnostic.lint] A lint check names a potentially undesirable coding pattern, such as unreachable code or omitted documentation. -r[attributes.diagnostics.lints.level] +r[attributes.diagnostic.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 @@ -20,22 +20,22 @@ to which the attribute applies. For any lint check `C`: -r[attributes.diagnostics.lints.allow] +r[attributes.diagnostic.lint.allow] * `#[allow(C)]` overrides the check for `C` so that violations will go unreported. -r[attributes.diagnostics.lints.expect] +r[attributes.diagnostic.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.lints.warn] +r[attributes.diagnostic.lint.warn] * `#[warn(C)]` warns about violations of `C` but continues compilation. -r[attributes.diagnostics.lints.deny] +r[attributes.diagnostic.lint.deny] * `#[deny(C)]` signals an error after encountering a violation of `C`, -r[attributes.diagnostics.lints.forbid] +r[attributes.diagnostic.lint.forbid] * `#[forbid(C)]` is the same as `deny(C)`, but also forbids changing the lint level afterwards, @@ -58,7 +58,7 @@ pub mod m1 { } ``` -r[attributes.diagnostics.lints.override] +r[attributes.diagnostic.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). @@ -106,7 +106,7 @@ pub mod m3 { ### Lint Reasons -r[attributes.diagnostics.lints.reason] +r[attributes.diagnostic.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. @@ -143,9 +143,9 @@ pub fn get_path() -> PathBuf { ### The `#[expect]` attribute -r[attributes.diagnostics.expect] +r[attributes.diagnostic.expect] -r[attributes.diagnostics.expect.general] +r[attributes.diagnostic.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 @@ -171,7 +171,7 @@ fn main() { } ``` -r[attributes.lints.expect.fulfilment] +r[attributes.lints.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 @@ -201,7 +201,7 @@ fn select_song() { } ``` -r[attributes.diagnostics.expect.independent] +r[attributes.diagnostic.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: @@ -230,7 +230,7 @@ pub fn another_example() { ### Lint groups -r[attributes.lints.groups] +r[attributes.diagnostic.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. @@ -251,7 +251,7 @@ fn example() { } ``` -r[attributes.lints.warnings-group] +r[attributes.diagnostic.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. @@ -271,13 +271,13 @@ fn example_err() { ### Tool lint attributes -r[attributes.lints.tools] +r[attributes.diagnostic.lint.tool] -r[attributes.lints.tools.general] +r[attributes.diagnostic.lint.tool.intro] Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of certain tools. -r[attributes.lints.tools.activation] +r[attributes.diagnostic.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. @@ -305,14 +305,14 @@ fn foo() { ## The `deprecated` attribute -r[attributes.diagnostics.deprecated] +r[attributes.diagnostic.deprecated] -r[attributes.diagnostics.deprecated.general] +r[attributes.diagnostic.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.deprectead.syntax] +r[attributes.diagnostic.deprecated.syntax] The `deprecated` attribute has several forms: - `deprecated` --- Issues a generic message. @@ -326,7 +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.diagnostics.deprecated.application] +r[attributes.diagnostic.deprecated.application] 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 @@ -352,20 +352,20 @@ The [RFC][1270-deprecation.md] contains motivations and more details. ## The `must_use` attribute -r[attributes.diagnostics.must_use] +r[attributes.diagnostic.must_use] -r[attributes.diagnostics.must_use.application] +r[attributes.diagnostic.must_use.application] 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 ([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions], and [traits]. -r[attributes.diagnostics.must_use.syntax] +r[attributes.diagnostic.must_use.syntax] 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.types] +r[attributes.diagnostic.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. @@ -384,7 +384,7 @@ struct MustUse { MustUse::new(); ``` -r[attributes.diagnostics.must_use.function] +r[attributes.diagnostic.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. @@ -397,7 +397,7 @@ fn five() -> i32 { 5i32 } five(); ``` -r[attributes.diagnostics.must_use.traits] +r[attributes.diagnostic.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. @@ -415,7 +415,7 @@ fn get_critical() -> impl Critical { get_critical(); ``` -r[attributes.diagnostics.must_use.trait-function] +r[attributes.diagnostic.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. @@ -433,7 +433,7 @@ impl Trait for i32 { 5i32.use_me(); ``` -r[attributes.diagnostics.must_use.impl-function] +r[attributes.diagnostic.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 @@ -468,59 +468,59 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -r[attributes.diagnostics.namespace] +r[attributes.diagnostic.namespace] -r[attributes.diagnostics.namespace.general] +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.diagnostics.namespace.unknown-invalid-syntax] +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.diagnostics.on_unimplemented] +r[attributes.diagnostic.on_unimplemented] -r[attributes.diagnostics.on_unimplemented.general] +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.diagnostics.on_unimplemented.restriction] +r[attributes.diagnostic.on_unimplemented.restriction] The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. -r[attributes.diagnostics.on_unimplemented.syntax] +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. -r[attributes.diagnostics.on_unimplemented.keys] +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.diagnostics.on_unimplemented-note-repetition] +r[attributes.diagnostic.on_unimplemented-note-repetition] The `note` option can appear several times, which results in several note messages being emitted. -r[attributes.diagnostics.on_unimplemented.repetition] +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.diagnostics.on_unimplemented.warnings] +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.diagnostics.format-string] +r[attributes.diagnostic.format-string] All three options accept a string as an argument, interpreted using the same formatting as a [`std::fmt`] string. -r[attributes.diagnostics.format-parameters] +r[attributes.diagnostic.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.diagnostics.invalid-formats] +r[attributes.diagnostic.invalid-formats] Any other format parameter will generate a warning, but will otherwise be included in the string as-is. -r[attributes.diagnostics.invalid-string] +r[attributes.diagnostic.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 b02e9c56a..edfff4aec 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -6,14 +6,14 @@ The following [attributes] affect compile-time limits. ## The `recursion_limit` attribute -r[attributes.limits.recursion_limits] +r[attributes.limits.recursion_limit] -r[attributes.limits.recursion_limits.application] +r[attributes.limits.recursion_limit.application] 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. -r[attributes.limits.recursion_limits.syntax] +r[attributes.limits.recursion_limit.syntax] It uses the [_MetaNameValueStr_] syntax to specify the recursion depth. @@ -49,7 +49,7 @@ r[attributes.limits.type_length_limit] > > For more information, see . -r[attributes.limits.type_length_limit.general] +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. diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 4d9706f60..c36029222 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -12,7 +12,7 @@ enables the [`test` conditional compilation option]. r[attributes.testing.test] -r[attributes.testing.test.general] +r[attributes.testing.test.intro] The *`test` attribute* marks a function to be executed as a test. r[attributes.testing.test.enabled] @@ -56,7 +56,7 @@ fn test_the_thing() -> io::Result<()> { r[attributes.testing.ignore] -r[attributes.testing.ignore.general] +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. diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index cccdba19f..ebbb8afc0 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -9,7 +9,7 @@ The following [attributes] are used for changing how a type can be used. r[attributes.type-system.non_exhaustive] -r[attributes.type-system.non_exhaustive.general] +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. From d3ef27783e5006115af34c469e1569e262863ef3 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Thu, 26 Sep 2024 14:32:01 -0400 Subject: [PATCH 12/18] Replace uses of `constraint` and `restriction` in attributes chapters. --- src/attributes/codegen.md | 2 +- src/attributes/debugger.md | 4 ++-- src/attributes/diagnostics.md | 2 +- src/attributes/limits.md | 2 +- src/attributes/testing.md | 4 ++-- src/attributes/type_system.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index cb27e214d..314b38fc8 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -86,7 +86,7 @@ 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.restriction-inline] +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. diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 40074b5c7..fb27af83f 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -12,7 +12,7 @@ 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.restriction] +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 @@ -23,7 +23,7 @@ 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.restrictions] +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] diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index dbbf6ce00..5e910c4a7 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -486,7 +486,7 @@ 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.restriction] +r[attributes.diagnostic.on_unimplemented.application] 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] diff --git a/src/attributes/limits.md b/src/attributes/limits.md index edfff4aec..7e06cb4cb 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -53,7 +53,7 @@ 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.restriction] +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 c36029222..5174d10ff 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -18,7 +18,7 @@ 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.restriction] +r[attributes.testing.test.target] Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: * `()` @@ -80,7 +80,7 @@ fn mytest() { r[attributes.testing.should_panic] -r[attributes.testing.should_panic.restriction] +r[attributes.testing.should_panic.target] A function annotated with the `test` attribute that returns `()` can also be annotated with the `should_panic` attribute. diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index ebbb8afc0..bce1b8a3c 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -13,7 +13,7 @@ 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. -r[attributes.type-system.non_exhaustive.restriction] +r[attributes.type-system.non_exhaustive.application] It can be applied to [`struct`s][struct], [`enum`s][enum], and `enum` variants. r[attributes.type-system.non_exhaustive.syntax] From ccbc70d85784e5c7d7ce0545deade738e9cfef29 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:25:53 -0800 Subject: [PATCH 13/18] Fix various spelling and format errors --- src/attributes/codegen.md | 10 +++++----- src/attributes/diagnostics.md | 10 +++++----- src/attributes/testing.md | 4 ++-- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 314b38fc8..4c5b96632 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -21,7 +21,7 @@ have no effect on a trait function without a body. ### The `inline` attribute -r[attributes.codgen.inline] +r[attributes.codegen.inline] r[attributes.codegen.inline.intro] The *`inline` [attribute]* suggests that a copy of the attributed function @@ -46,7 +46,7 @@ There are three ways to use the inline attribute: ### The `cold` attribute -r[attribute.codegen.cold] +r[attributes.codegen.cold] The *`cold` [attribute]* suggests that the attributed function is unlikely to be called. @@ -93,13 +93,13 @@ be used with a `target_feature` attribute. ### Available features -r[attributes.codegen.target_features.availability] +r[attributes.codegen.target_feature.availability] The following is a list of the available feature names. #### `x86` or `x86_64` -r[attributes.codegen.target_features.x86] +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` @@ -482,7 +482,7 @@ r[attributes.codegen.instruction_set] r[attributes.codegen.instruction_set.restriction] 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.behaviour] +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] diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 5e910c4a7..3a4b71258 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -499,7 +499,7 @@ The following keys have the given meaning: * `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] +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] @@ -509,18 +509,18 @@ 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.format-string] +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. -r[attributes.diagnostic.format-parameters] +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.invalid-formats] +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.invalid-string] +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/testing.md b/src/attributes/testing.md index 5174d10ff..6051dea8f 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -31,7 +31,7 @@ Test functions must be free, monomorphic functions that take no arguments, and t > Note: The test mode is enabled by passing the `--test` argument to `rustc` > or using `cargo test`. -r[attributes.testing.success] +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. @@ -84,7 +84,7 @@ r[attributes.testing.should_panic.target] A function annotated with the `test` attribute that returns `()` can also be annotated with the `should_panic` attribute. -r[attributes.testing.should_panic.behaviour] +r[attributes.testing.should_panic.behavior] The *`should_panic` attribute* makes the test only pass if it actually panics. From e0f31a0077fc74e47505d95e660a6f25616f350a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:26:10 -0800 Subject: [PATCH 14/18] Add back some newlines that were removed --- src/attributes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/attributes.md b/src/attributes.md index 02588b270..d1034ec19 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -48,6 +48,7 @@ The following attributes are unsafe: r[attributes.kind] Attributes can be classified into the following kinds: + * [Built-in attributes] * [Macro attributes][attribute macros] * [Derive macro helper attributes] @@ -55,6 +56,7 @@ Attributes can be classified into the following kinds: r[attributes.application] Attributes may be applied to many things in the language: + * All [item declarations] accept outer attributes while [external blocks], [functions], [implementations], and [modules] accept inner attributes. * Most [statements] accept outer attributes (see [Expression Attributes] for From da65af028d492b14f16473bcd3fd1688913306e7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:26:42 -0800 Subject: [PATCH 15/18] Remove some double blank lines --- src/attributes.md | 1 - src/attributes/codegen.md | 1 - src/attributes/debugger.md | 2 -- src/attributes/derive.md | 1 - src/attributes/diagnostics.md | 1 - src/attributes/testing.md | 2 -- src/attributes/type_system.md | 1 - 7 files changed, 9 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index d1034ec19..ee38dcd05 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -109,7 +109,6 @@ fn some_unused_variables() { 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: diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 4c5b96632..18fa36fc2 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -63,7 +63,6 @@ assumed to exist. 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 diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index fb27af83f..2521c4e83 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -86,7 +86,6 @@ When viewed under WinDbg, the `fancy_rect` variable would be shown as follows: 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]. @@ -161,7 +160,6 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil 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. diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 07238c44e..6a61dbf78 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -2,7 +2,6 @@ r[attributes.derive] - r[attributes.derive.intro] The *`derive` attribute* allows new [items] to be automatically generated for data structures. diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 3a4b71258..df7d16602 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -492,7 +492,6 @@ The attribute should be placed on a [trait declaration], though it is not an err 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. - r[attributes.diagnostic.on_unimplemented.keys] The following keys have the given meaning: * `message` --- The text for the top level error message. diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 6051dea8f..2d4ffaf1e 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -11,7 +11,6 @@ enables the [`test` conditional compilation option]. r[attributes.testing.test] - r[attributes.testing.test.intro] The *`test` attribute* marks a function to be executed as a test. @@ -55,7 +54,6 @@ fn test_the_thing() -> io::Result<()> { 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 diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index bce1b8a3c..5325a8870 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -8,7 +8,6 @@ The following [attributes] are used for changing how a type can be used. 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. From b62fbd27f3e9548603fff6d960c770295004ece8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:27:23 -0800 Subject: [PATCH 16/18] Remove annotations from the attribute index This is just for navigation, these aren't specific rules. --- src/attributes.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index ee38dcd05..e63866e39 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -240,24 +240,20 @@ r[attributes.builtin] The following is an index of all built-in attributes. -r[attributes.builtin.cfg] - Conditional compilation - [`cfg`] --- Controls conditional compilation. - [`cfg_attr`] --- Conditionally includes attributes. -r[attributes.builtin.testing] - Testing - [`test`] --- Marks a function as a test. - [`ignore`] --- Disables a test function. - [`should_panic`] --- Indicates a test should generate a panic. -r[attributes.builtin.derive] - Derive - [`derive`] --- Automatic trait implementations. - [`automatically_derived`] --- Marker for implementations created by `derive`. -r[attributes.builtin.macros] - Macros - [`macro_export`] --- Exports a `macro_rules` macro for cross-crate usage. - [`macro_use`] --- Expands macro visibility, or imports macros from other @@ -266,7 +262,6 @@ r[attributes.builtin.macros] - [`proc_macro_derive`] --- Defines a derive macro. - [`proc_macro_attribute`] --- Defines an attribute macro. -r[attributes.builtin.diagnostic] - Diagnostics - [`allow`], [`expect`], [`warn`], [`deny`], [`forbid`] --- Alters the default lint level. - [`deprecated`] --- Generates deprecation notices. @@ -274,7 +269,6 @@ r[attributes.builtin.diagnostic] - [`diagnostic::on_unimplemented`] --- Hints the compiler to emit a certain error message if a trait is not implemented. -r[attributes.builtin.linkage] - 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 @@ -294,7 +288,6 @@ r[attributes.builtin.linkage] object file. - [`crate_name`] --- Specifies the crate name. -r[attributes.builtin.codegen] - Code generation - [`inline`] --- Hint to inline code. - [`cold`] --- Hint that a function is unlikely to be called. @@ -303,43 +296,35 @@ r[attributes.builtin.codegen] - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`. - [`instruction_set`] - Specify the instruction set used to generate a functions code -r[attributes.builtin.doc] - Documentation - `doc` --- Specifies documentation. See [The Rustdoc Book] for more information. [Doc comments] are transformed into `doc` attributes. -r[attributes.builtin.prelude] - Preludes - [`no_std`] --- Removes std from the prelude. - [`no_implicit_prelude`] --- Disables prelude lookups within a module. -r[attributes.builtin.module] - Modules - [`path`] --- Specifies the filename for a module. -r[attributes.builtin.limits] - Limits - [`recursion_limit`] --- Sets the maximum recursion limit for certain compile-time operations. - [`type_length_limit`] --- Sets the maximum size of a polymorphic type. -r[attributes.builtin.rt] - 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. -r[attributes.builtin.unstable] - Features - `feature` --- Used to enable unstable or experimental compiler features. See [The Unstable Book] for features implemented in `rustc`. -r[attributes.builtin.typesystem] - Type System - [`non_exhaustive`] --- Indicate that a type will have more fields/variants added in future. -r[attributes.builtin.debugging] - Debugger - [`debugger_visualizer`] --- Embeds a file that specifies debugger output for a type. - [`collapse_debuginfo`] --- Controls how macro invocations are encoded in debuginfo. From d1232b4abcf0562d928d100f7167a62dc9beabe0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:31:35 -0800 Subject: [PATCH 17/18] Change a few rule names These are some misc rule name changes. Some of them are to give the rules more specific names (indicating what they do, instead of using generic terms). The `allowed-positions` name is intended to be used for all attributes to have a specific rule that defines where an attribute may be used. It is not consistently used, yet. Also, some of the paragraphs mix "where it goes" with "what it does" that should probably be teased apart so that we can label those independently. I expect us to do some more cleanup to bring some consistency to the attribute rules since there are a lot of attributes, and they generally have the same requirements of what needs to be specified. --- src/attributes.md | 2 +- src/attributes/codegen.md | 6 +++--- src/attributes/diagnostics.md | 13 ++++++++----- src/attributes/limits.md | 2 +- src/attributes/testing.md | 4 ++-- src/attributes/type_system.md | 2 +- 6 files changed, 16 insertions(+), 13 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index e63866e39..399a8852a 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -54,7 +54,7 @@ Attributes can be classified into the following kinds: * [Derive macro helper attributes] * [Tool attributes](#tool-attributes) -r[attributes.application] +r[attributes.allowed-position] Attributes may be applied to many things in the language: * All [item declarations] accept outer attributes while [external blocks], diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 18fa36fc2..3e24a3297 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -80,7 +80,7 @@ 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.precondition] +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. @@ -344,7 +344,7 @@ in the standard library for runtime feature detection on these platforms. r[attributes.codegen.track_caller] -r[attributes.codegen.track_caller.restriction] +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`. @@ -478,7 +478,7 @@ trait object whose methods are attributed. r[attributes.codegen.instruction_set] -r[attributes.codegen.instruction_set.restriction] +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] diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index df7d16602..8b3ad9249 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -326,7 +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.application] +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 @@ -354,13 +354,16 @@ The [RFC][1270-deprecation.md] contains motivations and more details. r[attributes.diagnostic.must_use] -r[attributes.diagnostic.must_use.application] +r[attributes.diagnostic.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.diagnostic.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.diagnostic.must_use.syntax] +r[attributes.diagnostic.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. @@ -486,7 +489,7 @@ 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.application] +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] diff --git a/src/attributes/limits.md b/src/attributes/limits.md index 7e06cb4cb..1c8c46bb5 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -8,7 +8,7 @@ The following [attributes] affect compile-time limits. r[attributes.limits.recursion_limit] -r[attributes.limits.recursion_limit.application] +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. diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 2d4ffaf1e..d245da66b 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -17,7 +17,7 @@ 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.target] +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: * `()` @@ -78,7 +78,7 @@ fn mytest() { r[attributes.testing.should_panic] -r[attributes.testing.should_panic.target] +r[attributes.testing.should_panic.intro] A function annotated with the `test` attribute that returns `()` can also be annotated with the `should_panic` attribute. diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index 5325a8870..e26de1210 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -12,7 +12,7 @@ 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. -r[attributes.type-system.non_exhaustive.application] +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] From 4ef5f5d93607f3da0a12fe76544c2b5d44787596 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 15 Nov 2024 13:42:30 -0800 Subject: [PATCH 18/18] Use plural `diagnostics` for diagnostics chapter This is keeping in line with using plurals throughout the rest of the naming convention. This also differentiates it from the `diagnostic` namespace. The `diagnostic` namespace remains singular, and is not nested with the plural `diagnostics` just to avoid the repetition. --- src/attributes/diagnostics.md | 62 +++++++++++++++++------------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 8b3ad9249..eb5caf2e6 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -1,18 +1,18 @@ # Diagnostic attributes -r[attributes.diagnostic] +r[attributes.diagnostics] The following [attributes] are used for controlling or generating diagnostic messages during compilation. ## Lint check attributes -r[attributes.diagnostic.lint] +r[attributes.diagnostics.lint] A lint check names a potentially undesirable coding pattern, such as unreachable code or omitted documentation. -r[attributes.diagnostic.lint.level] +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 @@ -20,22 +20,22 @@ to which the attribute applies. For any lint check `C`: -r[attributes.diagnostic.lint.allow] +r[attributes.diagnostics.lint.allow] * `#[allow(C)]` overrides the check for `C` so that violations will go unreported. -r[attributes.diagnostic.lint.expect] +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.diagnostic.lint.warn] +r[attributes.diagnostics.lint.warn] * `#[warn(C)]` warns about violations of `C` but continues compilation. -r[attributes.diagnostic.lint.deny] +r[attributes.diagnostics.lint.deny] * `#[deny(C)]` signals an error after encountering a violation of `C`, -r[attributes.diagnostic.lint.forbid] +r[attributes.diagnostics.lint.forbid] * `#[forbid(C)]` is the same as `deny(C)`, but also forbids changing the lint level afterwards, @@ -58,7 +58,7 @@ pub mod m1 { } ``` -r[attributes.diagnostic.lint.override] +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). @@ -106,7 +106,7 @@ pub mod m3 { ### Lint Reasons -r[attributes.diagnostic.lint.reason] +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. @@ -143,9 +143,9 @@ pub fn get_path() -> PathBuf { ### The `#[expect]` attribute -r[attributes.diagnostic.expect] +r[attributes.diagnostics.expect] -r[attributes.diagnostic.expect.intro] +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 @@ -171,7 +171,7 @@ fn main() { } ``` -r[attributes.lints.expect.fulfillment] +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 @@ -201,7 +201,7 @@ fn select_song() { } ``` -r[attributes.diagnostic.expect.independent] +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: @@ -230,7 +230,7 @@ pub fn another_example() { ### Lint groups -r[attributes.diagnostic.lint.group] +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. @@ -251,7 +251,7 @@ fn example() { } ``` -r[attributes.diagnostic.lint.group.warnings] +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. @@ -271,13 +271,13 @@ fn example_err() { ### Tool lint attributes -r[attributes.diagnostic.lint.tool] +r[attributes.diagnostics.lint.tool] -r[attributes.diagnostic.lint.tool.intro] +r[attributes.diagnostics.lint.tool.intro] Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of certain tools. -r[attributes.diagnostic.lint.tool.activation] +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. @@ -305,14 +305,14 @@ fn foo() { ## The `deprecated` attribute -r[attributes.diagnostic.deprecated] +r[attributes.diagnostics.deprecated] -r[attributes.diagnostic.deprecated.intro] +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.diagnostic.deprecated.syntax] +r[attributes.diagnostics.deprecated.syntax] The `deprecated` attribute has several forms: - `deprecated` --- Issues a generic message. @@ -352,23 +352,23 @@ The [RFC][1270-deprecation.md] contains motivations and more details. ## The `must_use` attribute -r[attributes.diagnostic.must_use] +r[attributes.diagnostics.must_use] -r[attributes.diagnostic.must_use.intro] +r[attributes.diagnostics.must_use.intro] The *`must_use` attribute* is used to issue a diagnostic warning when a value is not "used". -r[attributes.diagnostic.must_use.allowed-positions] +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.diagnostic.must_use.message] +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.diagnostic.must_use.type] +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. @@ -387,7 +387,7 @@ struct MustUse { MustUse::new(); ``` -r[attributes.diagnostic.must_use.fn] +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. @@ -400,7 +400,7 @@ fn five() -> i32 { 5i32 } five(); ``` -r[attributes.diagnostic.must_use.trait] +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. @@ -418,7 +418,7 @@ fn get_critical() -> impl Critical { get_critical(); ``` -r[attributes.diagnostic.must_use.trait-function] +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. @@ -436,7 +436,7 @@ impl Trait for i32 { 5i32.use_me(); ``` -r[attributes.diagnostic.must_use.trait-impl-function] +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