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

Merged
merged 8 commits into from
Dec 20, 2024
Merged

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

merged 8 commits into from
Dec 20, 2024

Conversation

weiznich
Copy link
Contributor

Documentation for rust-lang/rust#132056

@weiznich weiznich mentioned this pull request Oct 24, 2024
Merged
@ehuss ehuss added the S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository label Oct 24, 2024
ehuss
ehuss reviewed Oct 24, 2024
View reviewed changes
src/attributes/diagnostics.md Outdated
@@ -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.

@rustbot

This comment has been minimized.

Sign in to view
@rustbot rustbot added the S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. label Dec 3, 2024
weiznich and others added 3 commits December 6, 2024 08:07
@weiznich
Merge branch 'master' into do_not_recommend
8c9da69
@ehuss
Update do_not_recommend docs
3465b25 
A few updates for the docs here:

- Fix mistake using wrong attribute name
- Add annotations
- Try to clarify what kind of behavior the attribute has
- Separate allowed-positions, and syntax as separate concerns.
@ehuss
Add missing period and do not wrap
f28b8e8
@ehuss
Copy link
Contributor

ehuss commented Dec 12, 2024

@weiznich I was wondering if you could help me come up with a slightly more realistic example that demonstrates an improvement in the diagnostics? I feel like the example in the RFC at https://github.com/rust-lang/rfcs/blob/master/text/2397-do-not-recommend.md#guide-level-explanation is really close. It mentions "Perhaps when a function expects Bar and it's not implemented, it would never make sense to implement Foo for that type.", but I can't immediately think of an example where "it would never make sense to implement Foo". Is there maybe a way to relate the example to a realistic scenario?

@ehuss
Some more elaboration on do_not_recommend
6fc4148 
This adds some more explanation about the use of
`diagnostic::do_not_recommend`, with the intent of helping the reader to
understand how to use it. This also breaks that discussion out into a
note.

This also adds a before/after to the example to better show how it
changes.
@traviscross
Copy link
Contributor

Specifically also, it would help to have a minimal self-contained example.

@weiznich
Copy link
Contributor Author

The rustc test suite has several more relatistic examples:

Both examples are quite a bit larger than he trivial one, that's the reason why I've not used the here.

It mentions "Perhaps when a function expects Bar and it's not implemented, it would never make sense to implement Foo for that type.", but I can't immediately think of an example where "it would never make sense to implement Foo". Is there maybe a way to relate the example to a realistic scenario?

I think the wording is a bit too absolute here, in both cases linked above it's not that the suggested bound is never that one that the user want's. It's only that in almost all cases (for diesel something like >95%) the wrong suggestion that points users into the wrong direction. But there are edge cases where the current (without #[diagnostic::do_not_recommend]) suggestions are valid.

ehuss added 2 commits December 15, 2024 15:09
@ehuss
Soften the language to say "usually"
341cc83 
There may be times when the recommendation is useful, but the intent is
to use the attribute when it usually is not.
@ehuss
Rewrite do_not_recommend example
de346ad 
This rewrites the example to use a more realistic example that actually
demonstrates an improvement in the error message.
@ehuss
Copy link
Contributor

ehuss commented Dec 15, 2024

@weiznich Thanks! Both of those examples look pretty good, so I picked one that seemed like a pretty good demonstration.

Does the current wording seem accurate to you?

weiznich
weiznich commented Dec 16, 2024
View reviewed changes
Copy link
Contributor Author

@weiznich weiznich left a comment

Choose a reason for hiding this comment

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

Thanks for adding the more complex example. This sounds better now. I've left a minor comment about the wording otherwise this sounds good to me.

src/attributes/diagnostics.md Outdated Show resolved Hide resolved
@ehuss @weiznich
usually to normally
e4c6263 
Co-authored-by: Georg Semmler <github@weiznich.de>
ehuss
ehuss approved these changes Dec 16, 2024
View reviewed changes
Copy link
Contributor

@ehuss ehuss left a comment

Choose a reason for hiding this comment

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

Thanks!

src/attributes/diagnostics.md Outdated
@@ -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.

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

@ehuss ehuss added this pull request to the merge queue Dec 20, 2024
Merged via the queue into rust-lang:master with commit 1dffb2b Dec 20, 2024
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ehuss ehuss ehuss approved these changes

Assignees
No one assigned
Labels
S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@weiznich @rustbot @ehuss @traviscross