From 393fb601c9de624f9b26e80e42d0605e92f4c4ce Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jun 2025 08:23:02 -0700 Subject: [PATCH 1/7] Unwrap deprecated --- src/attributes/diagnostics.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index d1d1b65ddc..eb62be8c0b 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -303,30 +303,20 @@ r[attributes.diagnostics.deprecated] ## The `deprecated` attribute r[attributes.diagnostics.deprecated.intro] -The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue -warnings on use of `#[deprecated]` items. `rustdoc` will show item -deprecation, including the `since` version and `note`, if available. +The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue warnings on use of `#[deprecated]` items. `rustdoc` will show item deprecation, including the `since` version and `note`, if available. r[attributes.diagnostics.deprecated.syntax] The `deprecated` attribute has several forms: - `deprecated` --- Issues a generic message. -- `deprecated = "message"` --- Includes the given string in the deprecation - message. +- `deprecated = "message"` --- Includes the given string in the deprecation message. - [MetaListNameValueStr] syntax with two optional fields: - - `since` --- Specifies a version number when the item was deprecated. `rustc` - does not currently interpret the string, but external tools like [Clippy] - may check the validity of the value. - - `note` --- Specifies a string that should be included in the deprecation - message. This is typically used to provide an explanation about the - deprecation and preferred alternatives. + - `since` --- Specifies a version number when the item was deprecated. `rustc` does not currently interpret the string, but external tools like [Clippy] may check the validity of the value. + - `note` --- Specifies a string that should be included in the deprecation message. This is typically used to provide an explanation about the deprecation and preferred alternatives. r[attributes.diagnostic.deprecated.allowed-positions] -The `deprecated` attribute may be applied to any [item], [trait item], [enum -variant], [struct field], [external block item], or [macro definition]. It -cannot be applied to [trait implementation items][trait-impl]. When applied to an item -containing other items, such as a [module] or [implementation], all child -items inherit the deprecation attribute. +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][trait-impl]. When applied to an item containing other items, such as a [module] or [implementation], all child items inherit the deprecation attribute. + -Here is an example: -```rust -#[deprecated(since = "5.2.0", note = "foo was rarely used. Users should instead use bar")] -pub fn foo() {} -pub fn bar() {} -``` The [RFC][1270-deprecation.md] contains motivations and more details. From fa71ed60ab81a829edab5194d7b4c87c4d5e4a05 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jun 2025 13:27:11 -0700 Subject: [PATCH 3/7] Remove mention of RFC 1270 Looking at the RFC, it doesn't seem like it offers any particular insight or motivation that isn't already clear from what the attribute does. We still need a policy for how we refer to historical information like this, but generally I'd lean away from it. --- src/attributes/diagnostics.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 6c94ecdd0a..f558628a9a 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -330,13 +330,6 @@ The `deprecated` attribute may be applied to any [item], [trait item], [enum var Tuple struct fields are ignored. --> - - - -The [RFC][1270-deprecation.md] contains motivations and more details. - -[1270-deprecation.md]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md - r[attributes.diagnostics.must_use] ## The `must_use` attribute From d63553b6fb0fb84d9fd0266d1b315548a3a09f07 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jun 2025 13:29:40 -0700 Subject: [PATCH 4/7] Move the container behavior to a separate rule This is somewhat separate behavior, and I think it helps to discuss it separately. --- src/attributes/diagnostics.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index f558628a9a..6428499bce 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -323,13 +323,34 @@ The `deprecated` attribute has several forms: - `note` --- Specifies a string that should be included in the deprecation message. This is typically used to provide an explanation about the deprecation and preferred alternatives. r[attributes.diagnostic.deprecated.allowed-positions] -The `deprecated` attribute may be applied to any [item], [trait item], [enum variant], [struct field], [external block item], or [macro definition]. It cannot be applied to [trait implementation items][trait-impl]. When applied to an item containing other items, such as a [module] or [implementation], all child items inherit the deprecation attribute. +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][trait-impl]. +r[attributes.diagnostics.deprecated.containers] +When `deprecated` is applied to an item containing other items, all child items inherit the deprecation attribute. This includes: + +- [crate root] +- [modules] +- [implementations] +- [external blocks] + +> [!EXAMPLE] +> ```rust +> #[deprecated = "utility functions are no longer supported and will be removed in the future"] +> pub mod utils { +> pub fn trim() {} +> pub fn flush() {} +> } +> +> fn main() { +> utils::trim(); // WARNING: deprecated +> } +> ``` + r[attributes.diagnostics.must_use] ## The `must_use` attribute @@ -732,22 +753,24 @@ The first error message includes a somewhat confusing error message about the re [attributes]: ../attributes.md [block expression]: ../expressions/block-expr.md [call expression]: ../expressions/call-expr.md +[crate root]: ../crates-and-source-files.md [destructuring assignment]: expr.assign.destructure -[method call expression]: ../expressions/method-call-expr.md [dyn trait]: ../types/trait-object.md [enum variant]: ../items/enumerations.md [enumeration]: ../items/enumerations.md [expression statement]: ../statements.md#expression-statements [expression]: ../expressions.md [external block item]: ../items/external-blocks.md +[external blocks]: ../items/external-blocks.md [functions]: ../items/functions.md [impl trait]: ../types/impl-trait.md -[implementation]: ../items/implementations.md +[implementations]: ../items/implementations.md [item]: ../items.md [labeled block expressions]: ../expressions/block-expr.md#labeled-block-expressions [let statement]: ../statements.md#let-statements [macro definition]: ../macros-by-example.md -[module]: ../items/modules.md +[method call expression]: ../expressions/method-call-expr.md +[modules]: ../items/modules.md [rustc book]: ../../rustc/lints/index.html [rustc-lint-caps]: ../../rustc/lints/levels.html#capping-lints [rustc-lint-cli]: ../../rustc/lints/levels.html#via-compiler-flag From 3cac03258101dfef2197c4e23524ac7156710797 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jun 2025 13:32:31 -0700 Subject: [PATCH 5/7] Update `deprecated` to use the attribute template This updates it to use the attribute template format, and to split the behaviors of the different forms into different rules so they can be referenced. --- src/attributes/diagnostics.md | 102 ++++++++++++++++++++++++++++------ 1 file changed, 85 insertions(+), 17 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 6428499bce..a70ed02477 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -316,19 +316,86 @@ The *`deprecated` [attribute][attributes]* marks an item as deprecated. r[attributes.diagnostics.deprecated.syntax] The `deprecated` attribute has several forms: -- `deprecated` --- Issues a generic message. -- `deprecated = "message"` --- Includes the given string in the deprecation message. -- [MetaListNameValueStr] syntax with two optional fields: - - `since` --- Specifies a version number when the item was deprecated. `rustc` does not currently interpret the string, but external tools like [Clippy] may check the validity of the value. - - `note` --- Specifies a string that should be included in the deprecation message. This is typically used to provide an explanation about the deprecation and preferred alternatives. +```grammar,attributes +@root DeprecatedAttribute -> + `deprecated` `=` (STRING_LITERAL | RAW_STRING_LITERAL) + | `deprecated` `(` ( MetaNameValueStr (`,` MetaNameValueStr)* `,`? )? `)` + | `deprecated` +``` + +- The bare `deprecated` form generates a [generic message][attributes.diagnostics.deprecated.generic-message]. +- The `deprecated = "message"` form allows you to [specify a message][attributes.diagnostics.deprecated.message]. +- The `deprecated()` form allows you to [specify optional fields][attributes.diagnostics.deprecated.fields]. + +r[attributes.diagnostics.deprecated.allowed-positions] +The `deprecated` attribute may be applied to: +- [items] +- [trait items] +- [enum variants] +- [struct fields] (not including tuple struct fields) +- [external block items] +- [macro definitions] + +It may not be applied to [trait implementation items][trait-impl]. + +> [!NOTE] +> `rustc` currently ignores `deprecated` in other positions, but this may be rejected in the future. + +r[attributes.diagnostics.deprecated.duplicates] +The `deprecated` attribute may only be specified once on an item. + +r[attributes.diagnostics.deprecated.behavior] +A warning is emitted when a deprecated item is used. + + + +> [!EXAMPLE] +> ```rust +> #[deprecated = "use `bar` instead"] +> pub fn foo() {} +> +> fn main() { +> foo(); // WARNING: deprecated +> } +> ``` + +> [!NOTE] +> [Rustdoc] highlights when an item is deprecated, including the `since` and `note` if available. + +r[attributes.diagnostics.deprecated.generic-message] +The [MetaWord] form of the `deprecated` attribute generates a generic message in the diagnostic when the item is used. + +> [!EXAMPLE] +> ```rust +> #[deprecated] +> pub fn trim_left() {} +> ``` + +r[attributes.diagnostics.deprecated.message] +The [MetaNameValueStr] form of the `deprecated` attribute includes the given message in the diagnostic when the item is used. This is typically used to provide an explanation about the deprecation and preferred alternatives. + +> [!EXAMPLE] +> ```rust +> #[deprecated = "use `trim_start` instead"] +> pub fn trim_left() {} +> ``` + +r[attributes.diagnostics.deprecated.fields] +The [MetaListNameValueStr] form of the `deprecated` attribute allows you to specify two optional fields: -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][trait-impl]. +- `since` --- Specifies a version number when the item was deprecated. +- `note` --- Specifies a string that should be included in the deprecation message. This is equivalent to the message specified in the [MetaNameValueStr form][attributes.diagnostics.deprecated.message]. - +Each of these fields may only be specified at most once. + +> [!EXAMPLE] +> ```rust +> #[deprecated(since = "1.33.0", note = "use `trim_start` instead")] +> pub fn trim_left() {} +> ``` + +> [!NOTE] +> `rustc` does not currently interpret the `since` string, but external tools like [Clippy] may check the validity of the value. r[attributes.diagnostics.deprecated.containers] When `deprecated` is applied to an item containing other items, all child items inherit the deprecation attribute. This includes: @@ -756,11 +823,11 @@ The first error message includes a somewhat confusing error message about the re [crate root]: ../crates-and-source-files.md [destructuring assignment]: expr.assign.destructure [dyn trait]: ../types/trait-object.md -[enum variant]: ../items/enumerations.md [enumeration]: ../items/enumerations.md +[enum variants]: ../items/enumerations.md [expression statement]: ../statements.md#expression-statements [expression]: ../expressions.md -[external block item]: ../items/external-blocks.md +[external block items]: ../items/external-blocks.md [external blocks]: ../items/external-blocks.md [functions]: ../items/functions.md [impl trait]: ../types/impl-trait.md @@ -768,18 +835,19 @@ The first error message includes a somewhat confusing error message about the re [item]: ../items.md [labeled block expressions]: ../expressions/block-expr.md#labeled-block-expressions [let statement]: ../statements.md#let-statements -[macro definition]: ../macros-by-example.md [method call expression]: ../expressions/method-call-expr.md +[macro definitions]: ../macros-by-example.md [modules]: ../items/modules.md [rustc book]: ../../rustc/lints/index.html [rustc-lint-caps]: ../../rustc/lints/levels.html#capping-lints [rustc-lint-cli]: ../../rustc/lints/levels.html#via-compiler-flag -[rustdoc]: ../../rustdoc/lints.html -[struct field]: ../items/structs.md +[rustdoc]: ../../rustdoc/index.html +[rustdoc-lints]: ../../rustdoc/lints.html +[struct fields]: ../items/structs.md [struct]: ../items/structs.md [external block]: ../items/external-blocks.md [trait declaration]: ../items/traits.md -[trait item]: ../items/traits.md +[trait items]: ../items/traits.md [trait-impl]: ../items/implementations.md#trait-implementations [traits]: ../items/traits.md [uninhabited]: glossary.uninhabited From 5019296c3c4d19c43346d28e32eeb5d6dbccd67e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jun 2025 13:33:52 -0700 Subject: [PATCH 6/7] Add defaulted generic parameters for deprecated Support for this was added in https://github.com/rust-lang/rust/pull/77118 --- src/attributes/diagnostics.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index a70ed02477..8dfcedda37 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -335,6 +335,7 @@ The `deprecated` attribute may be applied to: - [struct fields] (not including tuple struct fields) - [external block items] - [macro definitions] +- [defaulted generic parameters] It may not be applied to [trait implementation items][trait-impl]. @@ -821,6 +822,7 @@ The first error message includes a somewhat confusing error message about the re [block expression]: ../expressions/block-expr.md [call expression]: ../expressions/call-expr.md [crate root]: ../crates-and-source-files.md +[defaulted generic parameters]: ../items/generics.md [destructuring assignment]: expr.assign.destructure [dyn trait]: ../types/trait-object.md [enumeration]: ../items/enumerations.md From 65c3b7a987ea3fd7a979518a951e04f25d960b0e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 12:47:02 -0700 Subject: [PATCH 7/7] Minor update of `deprecated` More closely align with the template, and some minor word tweaks. --- src/attributes/diagnostics.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 8dfcedda37..e847d88e68 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -299,6 +299,7 @@ fn foo() { > [!NOTE] > `rustc` currently recognizes the tool lints for "[clippy]" and "[rustdoc]". + r[attributes.diagnostics.deprecated] ## The `deprecated` attribute @@ -314,7 +315,7 @@ The *`deprecated` [attribute][attributes]* marks an item as deprecated. > ``` r[attributes.diagnostics.deprecated.syntax] -The `deprecated` attribute has several forms: +The syntax for the `deprecated` attribute is: ```grammar,attributes @root DeprecatedAttribute -> @@ -340,10 +341,10 @@ The `deprecated` attribute may be applied to: It may not be applied to [trait implementation items][trait-impl]. > [!NOTE] -> `rustc` currently ignores `deprecated` in other positions, but this may be rejected in the future. +> `rustc` ignores `deprecated` in other positions, but this may be rejected in the future. r[attributes.diagnostics.deprecated.duplicates] -The `deprecated` attribute may only be specified once on an item. +The `deprecated` attribute may only be used once on an item. r[attributes.diagnostics.deprecated.behavior] A warning is emitted when a deprecated item is used.