The #[diagnostic] attribute namespace

Author: weiznich

text/3366-diagnostic-attribute-namespace.md

@@ -0,0 +1,222 @@
+- Feature Name: The `#[diagnostic]` attribute namespace
+- Start Date: 2023-01-06
+- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)
+- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
+
+
+# Summary
+[summary]: #summary
+
+This RFC proposed to add a stable `#[diagnostic]` attribute namespace, which contains attributes to influence error messages emitted by the compiler. In addition it proposed to add a `#[diagnostic::on_unimplemented]` attribute to influence error messages emitted by unsatisfied traits bounds.
+
+# Motivation
+[motivation]: #motivation
+
+Rust has the reputation to generate helpful error messages when something goes wrong. Nevertheless there are always cases of error messages that can be improved. One common example of such error messages in the rust ecosystem are those that are generated by crates using the type system to verify certain invariants at compile time. While these crates provide additional guarantees about these invariants, they sometimes generate large incomprehensible error messages when something goes wrong. These error messages do not always indicate clearly what went wrong. Well known examples of crates with such issues include bevy, axum or diesel. In some situations such a specific error message always indicates a certain problem. By providing authors of such crates tools to control the error messages emitted by the compiler they can improve the situation on their own.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+This feature has two possible groups of users:
+
+* Users that develop code and consume error messages from the compiler
+* Users that write crates involving complex type hierarchies
+
+The first user group will interact with the proposed feature through the error messages emitted by the compiler. As of this I do not expect any major documentation requirements for this group of users. Although we might want to indicate that a certain error message was provided via the described feature set, rather than by the compiler itself to prevent users for filling issues about bad error messages in the compilers issue tracker.
+
+The second user group interacts with the described feature through attributes. These attributes allow them to hint the compiler to emit specific error messages in certain cases. The `#[diagnostic]` attribute namespace provides a general framework for what can and can't be done by such an attribute. As of this users won't interact directly with the attribute namespace itself. 
+
+The `#[diagnostic::on_unimplemented]` attribute allows to hint the compiler to emit a specific error message if a certain trait is not implemented. This attribute should provide the following interface:
+
+```rust
+#[diagnostic::on_unimplemented(
+    message="message",
+    label="label",
+    note="note"
+)]
+trait MyIterator<A> {
+    fn next(&mut self) -> A;
+}
+
+
+fn iterate_chars<I: MyIterator<char>>(i: I) {
+    // ...
+}
+fn main() {
+    iterate_chars(&[1, 2, 3][..]);
+}
+```
+
+which might result in the compiler emitting the following error message:
+
+```
+error[E0277]: message
+  --> <anon>:14:5
+   |
+14 |     iterate_chars(&[1, 2, 3][..]);
+   |     ^^^^^^^^^^^^^ label
+   |
+   = note: note
+   = help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
+   = note: required by `iterate_chars`
+```
+
+I expect the new attributes to be documented on the existing [Diagnostics](https://doc.rust-lang.org/reference/attributes/diagnostics.html) attributes page on the rust reference similar to existing attributes like for example `#[deprecated]`
+
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+## The `#[diagnostic]` attribute namespace
+
+This RFC proposes to introduce a new `#[diagnostic]` attribute namespace. This namespace is supposed to contain different attributes, which allow users to hint the compiler to emit specific error messages in certain cases like type mismatches, unsatisfied trait bounds or similar situations. By collecting such attributes in a common namespace it is easier for users to find useful attributes and it is easier for the language team to establish a set of common rules for these attributes.
+
+Any attribute in this namespace may:
+
+* Hint the compiler to emit a specific error message in a specific situation
+
+Any attribute in this namespace is not allowed to:
+
+* Change the result of the compilation, which means applying such an attribute should never cause an error as long as they are syntactically valid
+
+The compiler is allowed to:
+
+* Ignore the provided hints
+* Use only parts of the provided hints, for example for the proposed `#[diagnostic::on_unimplemented]` only use the `message` option
+* Change this behaviour at any time
+
+The compiler must:
+
+* Verify that the attribute is syntactically correct, which means:
+    + Its one of the accepted attributes
+    + It only contains the allowed options
+    + Any provided option follows the defined syntax
+* Follow the described semantics if the attribute is not ignored.
+
+
+## The `#[diagnostic::on_unimplemented]` attribute
+
+This section describes the syntax of the `on_unimplemented` attribute and additionally how it is supposed to work. Implementing the later part is optional as outlined in the previous section. Any syntax not explicitly described in this section must be rejected as invalid according to the general rules of the `#[diagnostic]` attribute namespace.
+
+```rust
+#[diagnostic::on_unimplemented(
+    message="message",
+    label="label",
+    note="note",
+)]
+trait MyIterator<A> {
+    fn next(&mut self) -> A;
+}
+```
+
+
+Each of the options `message`, `label` and `note` are optional. They are separated by comma. The tailing comma is optional. Specifying any of these options hints the compiler to replace the normally emitted part of the error message with the provided string. At least one of these options needs to exist. Each option can appear at most once. The error message can include type information for the `Self` type or any generic type by using `{Self}` or `{A}` (where `A` refers to the generic type name in the definition). These placeholders are replaced by the actual type name.
+
+In addition the `on_unimplemented` attribute provides mechanisms to specify for which exact types a certain message should be emitted via an `if()` option. It accepts a set of filter options. A filter option consists on the generic parameter name from the trait definition and a type path against which the parameter should be checked. These type path could either be a fully qualified path or refer to any type in the current scope. As a special generic parameter name `Self` is added to refer to the `Self` type of the trait implementation. A filter option evaluates to `true` if the corresponding generic parameter in the trait definition matches the specified type. The provided `message`/`note`/`label` options are only emitted if the filter operation evaluates to `true`.
+
+The `any` and `all` option allows to combine multiple filter options. The `any` option matches if one of the supplied filter options evaluates to `true`, the `all` option requires that all supplied filter options evaluate to true. `not` allows to negate a given filter option. It evaluates to `true` if the inner filter option evaluates to `false`. These options can be nested to construct complex filters.
+
+The `on_unimplemented` attribute can be applied multiple times to the same trait definition. Multiple attributes are evaluated in order. The first matching instance for each of the `message`/`label`/`note` options is emitted.
+```rust
+#[diagnostic::on_unimplemented(
+    if(Self = std::string::String),
+    note = "That's only emitted if Self == std::string::String"
+)]
+#[diagnostic::on_unimplemented(
+    if(A = String), // Refers to whatever `String` is in the current scope
+    note = "That's only emitted if A == String",
+)]
+#[diagnostic::on_unimplemented(
+    if(any(A = i32, Self = i32)),
+    note = "That's emitted if A or Self is a i32",
+)]
+// this attribute will not have any affect as
+// the attribute above will always match before
+#[diagnostic::on_unimplemented(
+    if(all(A = i32, Self = i32)),
+    note = "That's emitted if A and Self is a i32"
+)]
+#[diagnostic::on_unimplemented(
+    if(not(A = String)),
+    // and implicitly `A` is not a `i32` as that case is
+    // matched earlier
+    note = "That's emitted if A is not a `String`"
+)]
+#[diagnostic::on_unimplemented(
+    message="message",
+    label="label",
+    note="That's emitted if neither of the condition above are meet",
+)]
+trait MyIterator<A> {
+    fn next(&mut self) -> A;
+}
+```
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+A possible drawback is that this feature adds additional complexity to the compiler implementation. The compiler needs to handle an additional attribute namespace with at least one additional attribute. 
+
+Another drawback is that crates might hint lower quality error messages than the compiler itself. Technically the compiler would be free to ignore such hints, practically I would assume that it is impossible to judge the quality of such error messages in an automated way.
+
+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+This proposal tries to improve error messages generated by rustc. It would give crate authors a tool to influence what error message is emitted in a certain situation, as they might sometimes want to provide specific details on certain error conditions. Not implementing this proposal would result in the current status quo. Currently the compiler always shows a "general" error message, even if it would be helpful to show additional details.
+
+There are alternative designs for the proposed `on_unimplemented` attribute:
+
+* The `on()` based filtering might be replaceable by placing the attribute on negative trait impls. This would turn a filter like
+```rust
+#[diagnostic::on_unimplemented(
+    on(Self = `String`, message = "Strings do not implement `IntoIterator` directly")
+)]
+trait IntoIterator {}
+```
+
+into the following negative trait impl:
+```rust
+#[diagnostic::on_unimplemented(message = "Strings do not implement `IntoIterator` directly")]
+impl !IntoIterator for String {}
+```
+
+This would simplify the syntax of the proposed attribute, but in turn block the implementation of type based filtering on the stabilization of `negative_impls`. On the other hand it would likely simplify writing more complex filters, that match only a certain generic set of types and it would prevent "duplicating" the filter-logic as this reuses the exiting trait system. The large disadvantage of this approach is that it couples error messages to the crates public API. Removing a negative trait impl is a breaking change, removing a `#[on_unimplemented]` attribute is only a change in the emitted compiler error.
+
+* Allow `#[diagnostic::on_unimplemented]` to be placed on types instead of traits. This would allow third party crates to customize the error messages emitted for unsatisfied trait bounds with out of crate traits. This feels more like an extension tho the proposed attribute.
+
+# Prior art
+[prior-art]: #prior-art
+
+* [rustc_on_unimplemented](https://rustc-dev-guide.rust-lang.org/diagnostics.html#rustc_on_unimplemented) already provides the described functionality as rustc internal attribute. It is used for improving error messages for various standard library API's. [This repo](https://github.com/weiznich/rust-foundation-community-grant/) contains several examples on how this attribute can be used in external crates to improve their error messages.
+* [GHC](https://ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/type_errors.html) provides an Haskell language extension for specifying custom compile time errors
+
+Notably all of the listed similar features are unofficial language extensions.
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+Clarify the procedure of various potential changes prior stabilisation of the attribute namespace:
+
+* Process of adding a new attribute to the `#[diagnostics]` attribute macro namespace
+    + Requires a RFC? (t-lang seems to prefer that?)
+    + Requires a language/compiler MCP? 
+    + Just a PR to the compiler?
+* Process of extending an existing attribute by adding more options
+    + Requires a RFC?
+    + Requires a language/compiler MCP? 
+    + Just a PR to the compiler?
+* Process of removing support for specific options or an entire attribute from rustc
+    + Requires a compiler MCP? 
+    + Just a PR to the compiler?
+* Exact syntax of the `on_unimplemented` attribute
+    + Can `Self` be accepted in that position or do we need another name?
+    + Is `if()` a valid identifier in the proposed position?
+
+# Future possibilities
+[future-possibilities]: #future-possibilities
+
+* More attributes like `#[diagnostics::on_type_error]`
+* Extend the `#[diagnostics::on_unimplemented]` attribute to incorporate the semantics of `#[do_not_recommend]`
+* Un-RFC `#[do_not_recommend]`?
+* Apply `#[diagnostics::on_unimplemented]` to types as well
+* Extend the `if()` filter syntax to allow more complex filter expressions