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

weiznich · 2024-10-24T05:42:38Z

Documentation for rust-lang/rust#132056

ehuss · 2024-10-24T16:32:08Z

src/attributes/diagnostics.md

@@ -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.


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

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.

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 · 2024-12-12T21:27:51Z

@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?

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 · 2024-12-13T04:33:19Z

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

weiznich · 2024-12-13T09:44:17Z

The rustc test suite has several more relatistic examples:

AsExpression which was minimized from diesel
The tuple pyramid example which closely aligns with what bevy and also diesel want to do with quite a lot of "internal" implementations.

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.

There may be times when the recommendation is useful, but the intent is to use the attribute when it usually is not.

This rewrites the example to use a more realistic example that actually demonstrates an improvement in the error message.

ehuss · 2024-12-15T23:13:10Z

@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

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

Co-authored-by: Georg Semmler <[email protected]>

ehuss

Thanks!

ehuss · 2024-11-05T22:13:19Z

src/attributes/diagnostics.md

@@ -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.


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.

Update books ## rust-lang/book 13 commits in ad2011d3bcad9f152d034faf7635c22506839d58..04d06dfe541607e6419f3d028c3f9b245f3be4d9 2024-12-20 22:44:11 UTC to 2024-12-16 18:18:21 UTC - Update section name (rust-lang/book#4175) - Update text to reflect the change from '&str' to 'char' in example (rust-lang/book#4173) - Update figure number in text and file name (rust-lang/book#4172) - Fix chapter number (rust-lang/book#4171) - Delete unused reference (rust-lang/book#4170) - Remove orphaned half-sentence (rust-lang/book#4169) - Fix chapter number (rust-lang/book#4168) - A better phrasing for generic methods. (rust-lang/book#3428) - Fix minor grammatical error (rust-lang/book#4098) - Update appendix-06-translation.md to add another Chinese translation. (rust-lang/book#3608) - Change Korean translation repo to newer (rust-lang/book#3625) - Clarify/improve readability in Ch. 02 discussion of `Result` variants (rust-lang/book#4167) - Ch. 20: conclude §01 with a reference to the Rustonomicon (rust-lang/book#4166) ## rust-lang/nomicon 1 commits in 97e84a38c94bf9362b11284c20b2cb4adaa1e868..7ef05b9777c94836bc92f50f23e6e00981521a89 2024-12-30 10:38:10 UTC to 2024-12-30 10:38:10 UTC - Fix URL fragment to MutexGuard's negative impl of Send (rust-lang/nomicon#472) ## rust-lang/reference 3 commits in 9f41bc11342d46544ae0732caf14ec0bcaf27376..acd6794e712d5e2ef6f5c84fb95688d32a69b816 2024-12-18 23:04:30 +0000 to 2024-12-30 22:12:57 +0000 - Revert "`coverage` attribute" (rust-lang/reference#1706) - Document Rust 2024 match ergonomics reservations (rust-lang/reference#1702) - Add documentation for `#[diagnostic::do_not_recommend]` (rust-lang/reference#1663) ## rust-lang/edition-guide 5 commits in bc4ce51e1d4dacb9350a92e95f6159a42de2f8c6..d56e0f3a0656b7702ca466d4b191e16c28262b82 2024-12-18 05:34:59 +0000 to 2024-12-31 20:04:52 +0000 - 2024: Document rustfmt overflow_delimited_expr (rust-lang/edition-guide#352) - 2024: Document rustfmt fixes (rust-lang/edition-guide#351) - Update the transitioning steps (rust-lang/edition-guide#350) - Revert "2024: Assignment operator RHS indentation" (rust-lang/edition-guide#343) - Revert "2024: Add chapter on single-line `where` clauses" (rust-lang/edition-guide#344) ## rust-lang/rust-by-example 1 commits in 76406337f4131253443aea0ed7e7f451b464117c..093397535b48ae13ec76bc526b7e6eb8c096a85c 2024-12-18 17:29:56 UTC to 2024-12-18 17:29:56 UTC - Mention that you're not allowed to partially move Drop types (rust-lang/rust-by-example#1902) ## rust-lang/rustc-dev-guide 18 commits in 7f7ba48f04abc2ad25e52f30b5e2bffa286b019f..ad93c5f1c49f2aeb45f7a4954017b1e607df9f5e 2024-12-30 09:22:22 UTC to 2024-12-17 17:00:38 UTC - Opt into, rather than out of, linkcheck (rust-lang/rustc-dev-guide#2180) - Remove stale implementation details of coverage instrumentation (rust-lang/rustc-dev-guide#2179) - Remove properly tracked config file from .gitignore & add support for skipping of link-checking (rust-lang/rustc-dev-guide#2023) - Add a couple of linkcheck exceptions: (rust-lang/rustc-dev-guide#2120) - Add missing link for [Node] (rust-lang/rustc-dev-guide#2177) - Fix 403 received for HEAD request (rust-lang/rustc-dev-guide#2176) - Start using mdbook-linkcheck2 (rust-lang/rustc-dev-guide#2103) - Document `x test --no-capture` (rust-lang/rustc-dev-guide#2174) - Remove the `-test` suffix from normalize directives (rust-lang/rustc-dev-guide#2172) - Rework the driver docs (rust-lang/rustc-dev-guide#2162) - Document `forbid-output` for UI tests (rust-lang/rustc-dev-guide#2171) - completions: Zsh is now supported (rust-lang/rustc-dev-guide#2173) - region-outlives propagation (rust-lang/rustc-dev-guide#2169) - compiletest: Document the `--debugger` flag (rust-lang/rustc-dev-guide#2170) - document the public ci dashboard (rust-lang/rustc-dev-guide#2167) - Fix trivial typo of "query-fied" (rust-lang/rustc-dev-guide#2165) - Fix some typos (rust-lang/rustc-dev-guide#2166) - Add suggestion for `--keep-stage 0` (rust-lang/rustc-dev-guide#2164)

Add documentation for #[diagnostic::do_not_recommend]

09de1df

weiznich mentioned this pull request Oct 24, 2024

Stabilize #[diagnostic::do_not_recommend] rust-lang/rust#132056

Merged

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 reviewed Oct 24, 2024

View reviewed changes

This comment has been minimized.

Sign in to view

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

Merge branch 'master' into do_not_recommend

8c9da69

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.

Add missing period and do not wrap

f28b8e8

ehuss added 2 commits December 15, 2024 15:09

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.

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.

weiznich commented Dec 16, 2024

View reviewed changes

src/attributes/diagnostics.md Outdated Show resolved Hide resolved

usually to normally

e4c6263

Co-authored-by: Georg Semmler <[email protected]>

ehuss approved these changes Dec 16, 2024

View reviewed changes

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

rustbot mentioned this pull request Dec 30, 2024

Update books rust-lang/rust#134926

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

weiznich commented Oct 24, 2024

ehuss Oct 24, 2024

weiznich Oct 25, 2024

This comment has been minimized.

ehuss commented Dec 12, 2024

traviscross commented Dec 13, 2024

weiznich commented Dec 13, 2024

ehuss commented Dec 15, 2024

weiznich left a comment

ehuss left a comment

ehuss Nov 5, 2024

	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.

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

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

Conversation

weiznich commented Oct 24, 2024

ehuss Oct 24, 2024

Choose a reason for hiding this comment

weiznich Oct 25, 2024

Choose a reason for hiding this comment

This comment has been minimized.

ehuss commented Dec 12, 2024

traviscross commented Dec 13, 2024

weiznich commented Dec 13, 2024

ehuss commented Dec 15, 2024

weiznich left a comment

Choose a reason for hiding this comment

ehuss left a comment

Choose a reason for hiding this comment

ehuss Nov 5, 2024

Choose a reason for hiding this comment

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

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