Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation for #[diagnostic::do_not_recommend] #1663

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for #[diagnostic::do_not_recommend] #1663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,8 @@ The following is an index of all built-in attributes.
- [`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.
- [`diagnostic::do_not_recommend`] --- Hints the compiler to not show a certain trait
impl in error messages
- 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
Expand Down Expand Up @@ -371,3 +373,4 @@ The following is an index of all built-in attributes.
[function pointer]: types/function-pointer.md
[variadic functions]: items/external-blocks.html#variadic-functions
[`diagnostic::on_unimplemented`]: attributes/diagnostics.md#the-diagnosticon_unimplemented-attribute
[`diagnostic::do_not_recommend`]: attributes/diagnostics.md#the-diagnosticdo_not_recommend-attribute
41 changes: 41 additions & 0 deletions src/attributes/diagnostics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -492,6 +492,47 @@ error[E0277]: My Message for `ImportantTrait<i32>` implemented for `String`
= note: Note 2
```

### The `diagnostic::do_not_recommend` attribute

The `#[diagnostic::on_unimplemented]` attribute is a hint to the compiler to not show a certain trait implementation as part of the error message.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this explain a little more what error this is referring to, and what circumstances it will avoid showing an error?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this explain a little more what error this is referring to

Currently this is mostly relevant for E0277, although that might change in the future?

and what circumstances it will avoid showing an error?

It never avoids showing an error, it just changes the content of the error message to not mention/consider certain trait implementations if somewhat reasonable possible.

The attribute should be placed on a [trait implementation items]. It does not accept any arguments. If the attribute is placed in a wrong location or contains an unexpected argument the compiler might emit a warning and otherwise ignore the malformed part.

In this example:

```rust,compile_fail,E0277
trait Foo {}

#[diagnostic::do_not_recommend]
impl<T> Foo for T where T: Send {}

fn needs_foo<T: Foo>() {}

fn main() {
needs_foo::<*mut ()>();
}

```

the compiler may generate an error message which looks like this:

```text
error[E0277]: the trait bound `*mut (): Foo` is not satisfied
--> $DIR/simple.rs:15:17
|
LL | needs_foo::<*mut ()>();
| ^^^^^^^ the trait `Foo` is not implemented for `*mut ()`
|
note: required by a bound in `needs_foo`
--> $DIR/simple.rs:10:17
|
LL | fn needs_foo<T: Foo>() {}
| ^^^ required by this bound in `needs_foo`

error: aborting due to 1 previous error
```

Without the attribute the compiler would complain about `*mut (): Send` instead.

[Clippy]: https://github.com/rust-lang/rust-clippy
[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
[_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
Expand Down