From 33d76ea0339e80b3a2f5753bc3fac3c22df6d06b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:00:17 -0700 Subject: [PATCH 1/5] Move on_unimplemented example to the intro --- src/attributes/diagnostics.md | 70 ++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index fff0f3d632..75ddcf2606 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -479,6 +479,42 @@ 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. +> [!EXAMPLE] +> In this example: +> +> ```rust,compile_fail,E0277 +> #[diagnostic::on_unimplemented( +> message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", +> label = "My Label", +> note = "Note 1", +> note = "Note 2" +> )] +> trait ImportantTrait {} +> +> fn use_my_trait(_: impl ImportantTrait) {} +> +> fn main() { +> use_my_trait(String::new()); +> } +> ``` +> +> the compiler may generate an error message which looks like this: +> +> ```text +> error[E0277]: My Message for `ImportantTrait` implemented for `String` +> --> src/main.rs:14:18 +> | +> 14 | use_my_trait(String::new()); +> | ------------ ^^^^^^^^^^^^^ My Label +> | | +> | required by a bound introduced by this call +> | +> = help: the trait `ImportantTrait` is not implemented for `String` +> = note: Note 1 +> = note: Note 2 +> ``` + + 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. @@ -515,40 +551,6 @@ 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. -In this example: - -```rust,compile_fail,E0277 -#[diagnostic::on_unimplemented( - message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", - label = "My Label", - note = "Note 1", - note = "Note 2" -)] -trait ImportantTrait {} - -fn use_my_trait(_: impl ImportantTrait) {} - -fn main() { - use_my_trait(String::new()); -} -``` - -the compiler may generate an error message which looks like this: - -```text -error[E0277]: My Message for `ImportantTrait` implemented for `String` - --> src/main.rs:14:18 - | -14 | use_my_trait(String::new()); - | ------------ ^^^^^^^^^^^^^ My Label - | | - | required by a bound introduced by this call - | - = help: the trait `ImportantTrait` is not implemented for `String` - = note: Note 1 - = note: Note 2 -``` - r[attributes.diagnostic.do_not_recommend] ### The `diagnostic::do_not_recommend` attribute From 21a50dc79bdd82cc0538d0b416bc3da3130a7f21 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:08:20 -0700 Subject: [PATCH 2/5] Adjust on_unimplemented intro to use the attribute template --- src/attributes/diagnostics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 75ddcf2606..940511ca69 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -477,7 +477,7 @@ r[attributes.diagnostic.on_unimplemented] ### The `diagnostic::on_unimplemented` attribute 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. +The *`diagnostic::on_unimplemented` [attribute][attributes]* 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. > [!EXAMPLE] > In this example: From 5d31b3cc05db8be24897569c0a4b5f2c17146263 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:08:47 -0700 Subject: [PATCH 3/5] Move on_unimplemented syntax rule to be first --- src/attributes/diagnostics.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 940511ca69..69045ccb40 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -514,10 +514,6 @@ The *`diagnostic::on_unimplemented` [attribute][attributes]* is a hint to the co > = note: Note 2 > ``` - -r[attributes.diagnostic.on_unimplemented.allowed-positions] -The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. - r[attributes.diagnostic.on_unimplemented.syntax] The attribute uses the [MetaListNameValueStr] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. @@ -527,6 +523,9 @@ 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.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.note-repetition] The `note` option can appear several times, which results in several note messages being emitted. From 2348935a5fb6e8e6f35c2984f6a64a6ea7c0fae2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:09:15 -0700 Subject: [PATCH 4/5] Add attributes.diagnostic.on_unimplemented.duplicates --- src/attributes/diagnostics.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 69045ccb40..f9be92a0b6 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -526,6 +526,9 @@ The following keys have the given meaning: 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.duplicates] +If the `diagnostic::on_unimplemented` attribute is specified multiple times, then it behaves as if all options were specified in a single attribute. Duplicates of some options will be ignored, see [attributes.diagnostic.on_unimplemented.repetition]. + r[attributes.diagnostic.on_unimplemented.note-repetition] The `note` option can appear several times, which results in several note messages being emitted. From 74b595f425703bc7999f04d0877ff5104bb29cba Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 12:54:21 -0700 Subject: [PATCH 5/5] Minor update of `diagnostics::on_unimplemented` More closely align with the template, and some minor word tweaks. --- src/attributes/diagnostics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index f9be92a0b6..eb1f8e1849 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -473,6 +473,7 @@ Unknown attributes in this namespace are accepted, though they may emit warnings 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. + r[attributes.diagnostic.on_unimplemented] ### The `diagnostic::on_unimplemented` attribute @@ -524,7 +525,7 @@ The following keys have the given meaning: * `note` --- Provides additional notes. 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. +The `diagnostic::on_unimplemented` 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.duplicates] If the `diagnostic::on_unimplemented` attribute is specified multiple times, then it behaves as if all options were specified in a single attribute. Duplicates of some options will be ignored, see [attributes.diagnostic.on_unimplemented.repetition].