From 81fe01a11108a5e50bd51b7d22d638435ad687fd Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Thu, 18 Jan 2024 08:08:27 +0100 Subject: [PATCH 1/5] Add the `#[diagnostic]` attribute namespace and the `#[diagnostic::on_unimplemented]` feature to the reference --- src/attributes.md | 5 +++- src/attributes/diagnostics.md | 54 +++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index a1ad5c6..3b26a31 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -196,7 +196,7 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy" and "rustfmt". +> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostics". ## Built-in attributes index @@ -224,6 +224,8 @@ The following is an index of all built-in attributes. - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level. - [`deprecated`] — Generates deprecation notices. - [`must_use`] — Generates a lint for unused values. + - [`diagnostic::on_unimplemented`] - Hints the compiler to emit a certain error + message if a trait is not implemented. - ABI, linking, symbols, and FFI - [`link`] — Specifies a native library to link with an `extern` block. - [`link_name`] — Specifies the name of the symbol for functions or statics @@ -352,3 +354,4 @@ The following is an index of all built-in attributes. [closure]: expressions/closure-expr.md [function pointer]: types/function-pointer.md [variadic functions]: items/external-blocks.html#variadic-functions +[`diagnostic::on_unimplemented`]: attributes/diagnostics.md#the-diagnosticon_unimplemented-attribute diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 506e284..142b78f 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -301,6 +301,60 @@ When used on a function in a trait implementation, the attribute does nothing. > let _ = five(); > ``` +## The `diagnostic` tool attribute namespace + +The `#[diagnostic]` attribute namespace is meant to provide a home for attribute that allow users to influence error messages emitted by the compiler. The compiler is not guaranteed to use any of this hints, however it should accept any (non-)existing attribute in this namespace and potentially emit lint-warnings for unused attributes and options. This is meant to allow discarding certain attributes/options in the future to allow fundamental changes to the compiler without the need to keep then non-meaningful options working. + +### The `diagnostic::on_unimplemented` attribute + +The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This allows crate authors to hint the compiler to emit a specific worded error message if a certain trait is not implemented. The hinted message is supposed to replace the otherwise emitted error message. For the `#[diagnostic::on_unimplemented]` attribute the following options are implemented: + +* `message` which provides the text for the top level error message +* `label` which provides the text for the label shown inline in the broken code in the error message +* `note` which provides additional notes. + +The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. + +All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. For any non-existing argument a lint warning is generated. + +This allows to have a trait definition like: + +```rust +#[diagnostic::on_unimplemented( + message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", + label = "My Label", + note = "Note 1", + note = "Note 2" +)] +trait ImportantTrait {} +``` + +which then generates the for the following code + +```rust +fn use_my_trait(_: impl ImportantTrait) {} + +fn main() { + use_my_trait(String::new()); +} +``` + +this error message: + +``` +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 +``` + [Clippy]: https://github.com/rust-lang/rust-clippy [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax From 5baf87cdd925f4ca569570658d7fe55e783942ce Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Fri, 19 Jan 2024 08:11:40 +0000 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Eric Huss --- src/attributes.md | 4 ++-- src/attributes/diagnostics.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 3b26a31..1218fcb 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -196,7 +196,7 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostics". +> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostic". ## Built-in attributes index @@ -224,7 +224,7 @@ The following is an index of all built-in attributes. - [`allow`], [`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 + - [`diagnostic::on_unimplemented`] — Hints the compiler to emit a certain error message if a trait is not implemented. - ABI, linking, symbols, and FFI - [`link`] — Specifies a native library to link with an `extern` block. diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 142b78f..a704368 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -315,7 +315,7 @@ The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait de The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. For any non-existing argument a lint warning is generated. +All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. This allows to have a trait definition like: From 99b19d92c138d633c6ae9c41d863112def6c377a Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Fri, 19 Jan 2024 09:43:09 +0100 Subject: [PATCH 3/5] Apply more review suggestions manually Co-authored-by: Eric Huss --- src/attributes/diagnostics.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index a704368..c0c5c82 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -303,19 +303,29 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -The `#[diagnostic]` attribute namespace is meant to provide a home for attribute that allow users to influence error messages emitted by the compiler. The compiler is not guaranteed to use any of this hints, however it should accept any (non-)existing attribute in this namespace and potentially emit lint-warnings for unused attributes and options. This is meant to allow discarding certain attributes/options in the future to allow fundamental changes to the compiler without the need to keep then non-meaningful options working. +The `#[diagnostic]` attribute namespace is meant to provide a home for attributes to influence compile-time error messages. +The hints provides by these attributes are not guaranteed to be used. +Unknown attributes in this namespace are accepted, though tey may emit warings for unused attributes. +Additionally, invalid input 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 -The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This allows crate authors to hint the compiler to emit a specific worded error message if a certain trait is not implemented. The hinted message is supposed to replace the otherwise emitted error message. For the `#[diagnostic::on_unimplemented]` attribute the following options are implemented: +The `#[diagnostic::on_unimplemented]` attribute is designed to appear on trait definitions. +This attribute hints to hint the compiler to supplement a specific worded error message that would normally be generated in scenarios where the trait is required but not implemented on a type +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: * `message` which provides the text for the top level error message * `label` which provides the text for the label shown inline in the broken code in the error message * `note` which provides additional notes. -The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. +The `note` option can appear several times, which results in several note messages being emitted. +If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. +For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +All three options accept a text as argument. +This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax, where `{Self}` is resolved to the name of the type implementing the trait and `{NameOfGenericArgument}` is resolved to the relevant type name that replaces the `{NameOfGenericArgument}` argument if the error message is emitted. +Any other format parameter will generate a warning, but will otherwise be included in the string as-is. This allows to have a trait definition like: @@ -327,11 +337,7 @@ This allows to have a trait definition like: note = "Note 2" )] trait ImportantTrait {} -``` -which then generates the for the following code - -```rust fn use_my_trait(_: impl ImportantTrait) {} fn main() { @@ -339,7 +345,7 @@ fn main() { } ``` -this error message: +which might generate this error message: ``` error[E0277]: My Message for `ImportantTrait` implemented for `String` From 5e29b0135ed0353d7d9f4c2db9feba82f580cf50 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 12 Mar 2024 09:21:17 -0700 Subject: [PATCH 4/5] Various fixes and editing. --- src/attributes/diagnostics.md | 42 ++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index c0c5c82..45ed645 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -303,33 +303,39 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -The `#[diagnostic]` attribute namespace is meant to provide a home for attributes to influence compile-time error messages. -The hints provides by these attributes are not guaranteed to be used. -Unknown attributes in this namespace are accepted, though tey may emit warings for unused attributes. -Additionally, invalid input to known attributes will typically be a warning (see the attribute definitions for details). +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. +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 -The `#[diagnostic::on_unimplemented]` attribute is designed to appear on trait definitions. -This attribute hints to hint the compiler to supplement a specific worded error message that would normally be generated in scenarios where the trait is required but not implemented on a type -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: +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 attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. +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: -* `message` which provides the text for the top level error message -* `label` which provides the text for the label shown inline in the broken code in the error message -* `note` which provides additional notes. +* `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. -The `note` option can appear several times, which results in several note messages being emitted. -If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. +The `note` option can appear several times, which results in several note messages being emitted. +If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. +Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. -This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax, where `{Self}` is resolved to the name of the type implementing the trait and `{NameOfGenericArgument}` is resolved to the relevant type name that replaces the `{NameOfGenericArgument}` argument if the error message is emitted. +All three options accept a string as an argument. +The text in the string may contain the following format parameters which provide substitutions in the generated message: + +* `{Self}` — The name of the type implementing the trait. +* `{` *GenericParameterName* `}` — The name of the generic argument's type for the given generic parameter. + Any other format parameter will generate a warning, but will otherwise be included in the string as-is. -This allows to have a trait definition like: +In this example: -```rust +```rust,compile_fail,E0277 #[diagnostic::on_unimplemented( message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", label = "My Label", @@ -345,9 +351,9 @@ fn main() { } ``` -which might generate this error message: +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 | From 52874b8312ccbc28710a2532f82032876a08911b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 3 Apr 2024 14:29:34 -0700 Subject: [PATCH 5/5] Update on_unimplemented for format string changes. Updated in https://github.com/rust-lang/rust/pull/122402 --- src/attributes/diagnostics.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 45ed645..c636a96 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -325,14 +325,17 @@ If any of the other options appears several times the first occurrence of the re Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a string as an argument. -The text in the string may contain the following format parameters which provide substitutions in the generated message: +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: * `{Self}` — The name of the type implementing the trait. * `{` *GenericParameterName* `}` — The name of the generic argument's type for the given generic parameter. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +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 @@ -367,6 +370,7 @@ error[E0277]: My Message for `ImportantTrait` implemented for `String` = note: Note 2 ``` +[`std::fmt`]: ../../std/fmt/index.html [Clippy]: https://github.com/rust-lang/rust-clippy [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax