diff --git a/docs/attribute-template.md b/docs/attribute-template.md index 08c2d8d1c..07990e501 100644 --- a/docs/attribute-template.md +++ b/docs/attribute-template.md @@ -6,6 +6,7 @@ When an attribute (or a new attribute position in the grammar) is added, be sure ---- + r[PARENT.example] ## The `example` attribute @@ -14,7 +15,8 @@ The *`example` [attribute][attributes]* ...give a high level description. > [!EXAMPLE] > ```rust -> // This should be a very basic example showing the attribute used in some way. +> // This should be a very basic example showing the attribute +> // used in some way. > #[example] > fn some_meaningful_name() {} > ``` @@ -24,7 +26,7 @@ Describe the accepted syntax of this attribute. You can either explain that it u ---- -The `example` attribute uses the [MetaWord] syntax and thus does not take any inputs. +The `example` attribute uses the [MetaWord] syntax. ---- @@ -32,11 +34,62 @@ The `example` attribute uses the [MetaListPaths] syntax to specify a list of ... ---- +The `example` attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes. + +---- + +The `example` attribute uses the [MetaWord], [MetaListPaths], and [MetaNameValueStr] syntaxes. + +---- + +The `example` attribute uses the [MetaNameValueStr] syntax. Accepted values are `"X"` and `"Y"`. + +---- + +The `example` attribute uses the [MetaNameValueStr] syntax. The value in the string must be ... + +---- + +The `example` attribute has these forms: + +- [MetaWord] + > [!EXAMPLE] + > ```rust + > #[example] + > fn f() {} + > ``` + +- [MetaNameValueStr] --- The given string must ... + > [!EXAMPLE] + > ```rust + > #[example = "example"] + > fn f() {} + > ``` + +- [MetaListNameValueStr] --- As with the [MetaNameValueStr] syntax, the given string must ... + > [!EXAMPLE] + > ```rust + > #[example(inner = "example")] + > fn f() {} + > ``` + +---- + The syntax for the `example` attribute is: ```grammar,attributes @root ExampleAttribute -> `example` `(` ... `)` ``` +---- + +r[PARENT.example.syntax.foo] +The [MetaNameValueStr] form of the `example` attribute provides a way to specify the foo. + +> [!EXAMPLE] +> ```rust +> #[example = "example"] +> fn some_meaningful_name() {} +> ``` r[PARENT.example.allowed-positions] Explain the valid positions where this attribute may be used. @@ -60,10 +113,7 @@ The `example` attribute is allowed anywhere attributes are allowed. If there are unused attribute warnings, or if rustc is incorrectly accepting some positions, include a note about these. > [!NOTE] -> `rustc` currently warns in other positions, but this may be rejected in the future. - -> [!NOTE] -> `rustc` currently warns on some positions where it is ignored, but this may become an error in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. ---- @@ -72,29 +122,40 @@ Explain the behavior if the attribute is specified multiple times on an element. ---- -Duplicate instances of the `example` attribute on the same ... have no effect. +The `example` attribute may be used any number of times on a form. ---- -The `example` attribute may only be specified once on a [THING]. +Using `example` more than once on a form has the same effect as using it once. ---- -Only the first instance of `example` on an item is honored. Subsequent `example` attributes are ignored. +The `example` attribute may be used only once on ... + +---- + +Only the first use of `example` on an item has effect. + +> [!NOTE] +> `rustc` lints against any use following the first. This may become an error in the future. > [!NOTE] -> `rustc` currently warns on subsequent duplicate `example` attributes. This may become an error in the future. +> `rustc` lints against any use following the first with a future-compatibility warning. This may become an error in the future. ---- -Only the last instance of `example` on an item is honored. Previous `example` attributes are ignored. +Only the last use of `example` on an item has effect. > [!NOTE] -> `rustc` currently warns on preceding duplicate `example` attributes. This may become an error in the future. +> `rustc` lints against any use preceding the last. This may become an error in the future. ---- +---- + +Only the last use of `example` on an item is used to ... + +---- -If the `example` attribute is specified multiple times on an item, then the combination of all the specified values is used as ...explain how they are merged. +If the `example` attribute is used more than once on an item, then the combination of all the specified values is used as ...explain how they are merged. ---- diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 5bd711910..24e4c2c3a 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -82,6 +82,7 @@ The [`track_caller`](#the-track_caller-attribute) attribute cannot be applied to r[attributes.codegen.naked.testing] The [testing attributes](testing.md) cannot be applied to a naked function. + r[attributes.codegen.no_builtins] ## The `no_builtins` attribute @@ -105,7 +106,7 @@ r[attributes.codegen.no_builtins.duplicates] Only the first use of the `no_builtins` attribute has effect. > [!NOTE] -> `rustc` currently lints against uses following the first. +> `rustc` lints against any use following the first. r[attributes.codegen.target_feature] ## The `target_feature` attribute diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 9f2a3532e..6fe1792e5 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -1,3 +1,4 @@ + r[attributes.derive] # Derive @@ -36,10 +37,10 @@ r[attributes.derive.syntax] The `derive` attribute uses the [MetaListPaths] syntax to specify a list of paths to [derive macros] to invoke. r[attributes.derive.allowed-positions] -The `derive` attribute may be applied to [structs][items.struct], [enums][items.enum], and [unions][items.union]. +The `derive` attribute may only be applied to [structs][items.struct], [enums][items.enum], and [unions][items.union]. r[attributes.derive.duplicates] -The `derive` attribute may be specified multiple times on an item, with all derive macros listed in all attributes being invoked. +The `derive` attribute may be used any number of times on an item. All derive macros listed in all attributes are invoked. r[attributes.derive.stdlib] The `derive` attribute is exported in the standard library prelude as [`core::prelude::v1::derive`]. @@ -63,6 +64,7 @@ The built-in derives include the [`automatically_derived` attribute][attributes. r[attributes.derive.behavior] During macro expansion, for each element in the list of derives, the corresponding derive macro expands to zero or more [items]. + r[attributes.derive.automatically_derived] ## The `automatically_derived` attribute @@ -84,19 +86,19 @@ The *`automatically_derived` [attribute][attributes]* is used to annotate an [im > ``` r[attributes.derive.automatically_derived.syntax] -The `automatically_derived` attribute uses the [MetaWord] syntax and so does not accept any arguments. +The `automatically_derived` attribute uses the [MetaWord] syntax. r[attributes.derive.automatically_derived.allowed-positions] -The `automatically_derived` attribute may be placed on an [implementation]. +The `automatically_derived` attribute may only be applied to an [implementation]. > [!NOTE] -> `rustc` currently accepts the attribute in other positions but lints against it. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[attributes.derive.automatically_derived.duplicates] -Duplicate instances of the `automatically_derived` attribute on the same implementation have no effect. +Using `automatically_derived` more than once on an implementation has the same effect as using it once. > [!NOTE] -> `rustc` lints against duplicate use of this attribute on uses following the first. +> `rustc` lints against any use following the first. r[attributes.derive.automatically_derived.behavior] The `automatically_derived` attribute has no behavior. diff --git a/src/attributes/limits.md b/src/attributes/limits.md index 0e1543116..bb88b872d 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -40,34 +40,48 @@ a!{} (|_: &u8| {})(&&&1); ``` + r[attributes.limits.type_length_limit] ## The `type_length_limit` attribute +r[attributes.limits.type_length_limit.intro] +The *`type_length_limit` [attribute][attributes]* sets the maximum number of type substitutions allowed when constructing a concrete type during monomorphization. + > [!NOTE] -> This limit is only enforced when the nightly `-Zenforce-type-length-limit` flag is active. +> `rustc` only enforces the limit when the nightly `-Zenforce-type-length-limit` flag is active. > -> For more information, see . +> For more information, see [Rust PR #127670](https://github.com/rust-lang/rust/pull/127670). -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. +> [!EXAMPLE] +> +> ```rust,ignore +> #![type_length_limit = "4"] +> +> fn f(x: T) {} +> +> // This fails to compile because monomorphizing to +> // `f::<((((i32,), i32), i32), i32)>` requires more +> // than 4 type elements. +> f(((((1,), 2), 3), 4)); +> ``` + +> [!NOTE] +> The default value in `rustc` is `1048576`. 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. +The `type_length_limit` attribute uses the [MetaNameValueStr] syntax. The value in the string must be a non-negative number. -> [!NOTE] -> The default in `rustc` is 1048576. +r[attributes.limits.type_length_limit.allowed-positions] +The `type_length_limit` attribute may only be applied to the crate root. -```rust,ignore -#![type_length_limit = "4"] +> [!NOTE] +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. -fn f(x: T) {} +r[attributes.limits.type_length_limit.duplicates] +Only the first use of `type_length_limit` on an item has effect. -// This fails to compile because monomorphizing to -// `f::<((((i32,), i32), i32), i32)>` requires more than 4 type elements. -f(((((1,), 2), 3), 4)); -``` +> [!NOTE] +> `rustc` lints against any use following the first. This may become an error in the future. [attributes]: ../attributes.md [crate]: ../crates-and-source-files.md diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 8fbceddab..87d43453d 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -6,6 +6,7 @@ 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 enables the [`test` conditional compilation option]. + r[attributes.testing.test] ## The `test` attribute @@ -23,7 +24,7 @@ The *`test` [attribute][attributes]* marks a function to be executed as a test. > ``` r[attributes.testing.test.syntax] -The `test` attribute uses the [MetaWord] syntax and thus does not take any inputs. +The `test` attribute uses the [MetaWord] syntax. r[attributes.testing.test.allowed-positions] The `test` attribute may only be applied to [free functions] that are monomorphic, that take no arguments, and where the return type implements the [`Termination`] trait. @@ -34,10 +35,10 @@ The `test` attribute may only be applied to [free functions] that are monomorphi > * `Result where T: Termination, E: Debug` r[attributes.testing.test.duplicates] -Only the first instance of `test` on a function is honored. +Only the first use of `test` on a function has effect. > [!NOTE] -> Subsequent `test` attributes are currently ignored and `rustc` warns about these. +> `rustc` lints against any use following the first. This may become an error in the future. @@ -71,6 +72,7 @@ In particular: > } > ``` + r[attributes.testing.ignore] ## The `ignore` attribute @@ -90,7 +92,7 @@ The *`ignore` [attribute][attributes]* can be used with the [`test` attribute][a > The `rustc` test harness supports the `--include-ignored` flag to force ignored tests to be run. r[attributes.testing.ignore.syntax] -The `ignore` attribute uses either the [MetaWord] or [MetaNameValueStr] syntax. +The `ignore` attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes. r[attributes.testing.ignore.reason] The [MetaNameValueStr] form of the `ignore` attribute provides a way to specify a reason why the test is ignored. @@ -105,20 +107,21 @@ The [MetaNameValueStr] form of the `ignore` attribute provides a way to specify > ``` r[attributes.testing.ignore.allowed-positions] -The `ignore` attribute may be applied to functions annotated with the `test` attribute. +The `ignore` attribute may only be applied to functions annotated with the `test` attribute. > [!NOTE] -> `rustc` currently warns when `ignore` is used in some other situations. This may become an error in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[attributes.testing.ignore.duplicates] -Only the first instance of `ignore` on a function is honored. +Only the first use of `ignore` on a function has effect. > [!NOTE] -> `rustc` currently ignores duplicate `ignore` attributes. This may become an error in the future. +> `rustc` lints against any use following the first. This may become an error in the future. r[attributes.testing.ignore.behavior] Ignored tests are still compiled when in test mode, but they are not executed. + r[attributes.testing.should_panic] ## The `should_panic` attribute @@ -135,7 +138,7 @@ The *`should_panic` [attribute][attributes]* causes a test to pass only if the [ > ``` r[attributes.testing.should_panic.syntax] -The `should_panic` attribute has one of the following forms: +The `should_panic` attribute has these forms: - [MetaWord] > [!EXAMPLE] @@ -165,13 +168,13 @@ r[attributes.testing.should_panic.allowed-positions] The `should_panic` attribute may only be applied to functions annotated with the `test` attribute. > [!NOTE] -> `rustc` currently accepts this attribute in other positions with a warning. This may become a hard error in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[attributes.testing.should_panic.duplicates] -Only the first instance of `should_panic` on a function is honored. +Only the first use of `should_panic` on a function has effect. > [!NOTE] -> `rustc` currently ignores subsequent `should_panic` attributes and emits a future-compatibility warning. This may become a hard error in the future. +> `rustc` lints against any use following the first with a future-compatibility warning. This may become an error in the future. r[attributes.testing.should_panic.expected] When the [MetaNameValueStr] form or the [MetaListNameValueStr] form with the `expected` key is used, the given string must appear somewhere within the panic message for the test to pass. diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index d740194b6..213c5088f 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -315,6 +315,7 @@ Example values: ## Forms of conditional compilation + r[cfg.attr] ### The `cfg` attribute @@ -363,13 +364,13 @@ The syntax for the `cfg` attribute is: ``` r[cfg.attr.allowed-positions] -The `cfg` attribute is allowed anywhere attributes are allowed. +The `cfg` attribute may be used anywhere attributes are allowed. r[cfg.attr.duplicates] -Multiple `cfg` attributes may be specified. The form to which the attribute is attached will not be included if any of the `cfg` predicates are false except as described in [cfg.attr.crate-level-attrs]. +The `cfg` attribute may be used any number of times on a form. The form to which the attributes are attached will not be included if any of the `cfg` predicates are false except as described in [cfg.attr.crate-level-attrs]. r[cfg.attr.effect] -If the predicate is true, the form is rewritten to not have the `cfg` attribute on it. If the predicate is false, the form is removed from the source code. +If the predicates are true, the form is rewritten to not have the `cfg` attributes on it. If any predicate is false, the form is removed from the source code. r[cfg.attr.crate-level-attrs] When a crate-level `cfg` has a false predicate, the crate itself still exists. Any crate attributes preceding the `cfg` are kept, and any crate attributes following the `cfg` are removed as well as removing all of the following crate contents. @@ -388,6 +389,7 @@ When a crate-level `cfg` has a false predicate, the crate itself still exists. A > pub fn example() {} > ``` + r[cfg.cfg_attr] ### The `cfg_attr` attribute @@ -414,10 +416,10 @@ CfgAttrs -> Attr (`,` Attr)* `,`? ``` r[cfg.cfg_attr.allowed-positions] -The `cfg_attr` attribute is allowed anywhere attributes are allowed. +The `cfg_attr` attribute may be used anywhere attributes are allowed. r[cfg.cfg_attr.duplicates] -Multiple `cfg_attr` attributes may be specified. +The `cfg_attr` attribute may be used any number of times on a form. r[cfg.cfg_attr.attr-restriction] The [`crate_type`] and [`crate_name`] attributes cannot be used with `cfg_attr`. diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index 93a5f01d7..9e53ab4c0 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -73,6 +73,7 @@ r[items.extern-crate.underscore.macro_use] The [`macro_use` attribute] works as usual and imports the macro names into the [`macro_use` prelude]. + r[items.extern-crate.no_link] ## The `no_link` attribute @@ -92,19 +93,19 @@ The *`no_link` [attribute][attributes]* may be applied to an `extern crate` item > ``` r[items.extern-crate.no_link.syntax] -The `no_link` attribute uses the [MetaWord] syntax and so does not accept any arguments. +The `no_link` attribute uses the [MetaWord] syntax. r[items.extern-crate.no_link.allowed-positions] The `no_link` attribute may only be applied to an `extern crate` declaration. > [!NOTE] -> `rustc` currently accepts and ignores the attribute in other positions but lints against it. This may become a hard error in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[items.extern-crate.no_link.duplicates] -Duplicate instances of the `no_link` attribute are ignored. +Only the first use of `no_link` on an `extern crate` declaration has effect. > [!NOTE] -> `rustc` lints against duplicate use of this attribute. +> `rustc` lints against any use following the first. This may become an error in the future. [identifier]: ../identifiers.md [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 590a5ef28..c6163b07c 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -391,6 +391,7 @@ r[items.extern.attributes.link.import_name_type.platform-specific] The `import_name_type` key is only supported on x86 Windows. Using it when targeting other platforms will result in a compiler error. + r[items.extern.attributes.link_name] ### The `link_name` attribute @@ -412,13 +413,13 @@ r[items.extern.attributes.link_name.allowed-positions] The `link_name` attribute may only be applied to a function or static item in an `extern` block. > [!NOTE] -> `rustc` currently accepts and ignores the attribute in other positions but lints against it. This may become a hard error in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[items.extern.attributes.link_name.duplicates] -Only the last instance of `link_name` on an item is used to determine the symbol name. +Only the last use of `link_name` on an item has effect. > [!NOTE] -> `rustc` lints against duplicate use of this attribute on uses preceding the last. This may become a hard error in the future. +> `rustc` lints against any use preceding the last. This may become an error in the future. r[items.extern.attributes.link_name.link_ordinal] The `link_name` attribute may not be used with the [`link_ordinal`] attribute. diff --git a/src/procedural-macros.md b/src/procedural-macros.md index a26a57eb2..48f31369d 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -130,6 +130,7 @@ position, which includes [statements], [expressions], [patterns], [type expressions], [item] positions, including items in [`extern` blocks], inherent and trait [implementations], and [trait definitions]. + r[macro.proc.derive] ## The `proc_macro_derive` attribute @@ -185,7 +186,7 @@ r[macro.proc.derive.allowed-positions] The `proc_macro_derive` attribute may only be applied to a `pub` function with the [Rust ABI][items.fn.extern] defined in the root of the crate with a type of `fn(TokenStream) -> TokenStream` where [`TokenStream`] comes from the [`proc_macro` crate]. The function may be `const` and may use `extern` to explicitly specify the Rust ABI, but it may not use any other [qualifiers][FunctionQualifiers] (e.g. it may not be `async` or `unsafe`). r[macro.proc.derive.duplicates] -The `proc_macro_derive` attribute may be specified only once on a function. +The `proc_macro_derive` attribute may be used only once on a function. r[macro.proc.derive.namespace] The `proc_macro_derive` attribute publicly defines the derive macro in the [macro namespace] in the root of the crate. diff --git a/src/runtime.md b/src/runtime.md index 566985c53..8812216cb 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -3,6 +3,7 @@ r[runtime] This section documents features that define some aspects of the Rust runtime. + r[runtime.global_allocator] ## The `global_allocator` attribute @@ -44,6 +45,7 @@ The `global_allocator` attribute may only be used once in the crate graph. r[runtime.global_allocator.stdlib] The `global_allocator` attribute is exported from the [standard library prelude][core::prelude::v1]. + r[runtime.windows_subsystem] ## The `windows_subsystem` attribute @@ -62,10 +64,10 @@ r[runtime.windows_subsystem.allowed-positions] The `windows_subsystem` attribute may only be applied to the crate root. r[runtime.windows_subsystem.duplicates] -Only the first use of `windows_subsystem` is honored. +Only the first use of `windows_subsystem` has effect. > [!NOTE] -> `rustc` currently lints against uses following the first. This may become a hard error in the future. +> `rustc` lints against any use following the first. This may become an error in the future. r[runtime.windows_subsystem.ignored] The `windows_subsystem` attribute is ignored on non-Windows targets and non-`bin` [crate types].