You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `deprecated` attribute may be applied to any [item], [trait item], [enum
331
331
variant], [struct field], [external block item], or [macro definition]. It
332
-
cannot be applied to [trait implementation items]. When applied to an item
332
+
cannot be applied to [trait implementation items][trait-impl]. When applied to an item
333
333
containing other items, such as a [module] or [implementation], all child
334
334
items inherit the deprecation attribute.
335
335
<!-- NOTE: It is only rejected for trait impl items
@@ -559,6 +559,119 @@ error[E0277]: My Message for `ImportantTrait<i32>` implemented for `String`
559
559
= note: Note 2
560
560
```
561
561
562
+
### The `diagnostic::do_not_recommend` attribute
563
+
564
+
r[attributes.diagnostic.do_not_recommend]
565
+
566
+
r[attributes.diagnostic.do_not_recommend.intro]
567
+
The `#[diagnostic::do_not_recommend]` attribute is a hint to the compiler to not show the annotated trait implementation as part of a diagnostic message.
568
+
569
+
> **Note**: Suppressing the recommendation can be useful if you know that the recommendation would normally not be useful to the programmer. This often occurs with broad, blanket impls. The recommendation may send the programmer down the wrong path, or the trait implementation may be an internal detail that you don't want to expose, or the bounds may not be able to be satisfied by the programmer.
570
+
>
571
+
> For example, in an error message about a type not implementing a required trait, the compiler may find a trait implementation that would satisfy the requirements if it weren't for specific bounds in the trait implementation. The compiler may tell the user that there is an impl, but the problem is the bounds in the trait implementation. The `#[diagnostic::do_not_recommend]` attribute can be used to tell the compiler to *not* tell the user about the trait implementation, and instead simply tell the user the type doesn't implement the required trait.
The attribute should be placed on a [trait implementation item][trait-impl], though it is not an error to be located in other positions.
575
+
576
+
r[attributes.diagnostic.do_not_recommend.syntax]
577
+
The attribute does not accept any arguments, though unexpected arguments are not considered as an error.
578
+
579
+
In the following example, there is a trait called `AsExpression` which is used for casting arbitrary types to the `Expression` type used in an SQL library. There is a method called `check` which takes an `AsExpression`.
580
+
581
+
```rust,compile_fail,E0277
582
+
# pub trait Expression {
583
+
# type SqlType;
584
+
# }
585
+
#
586
+
# pub trait AsExpression<ST> {
587
+
# type Expression: Expression<SqlType = ST>;
588
+
# }
589
+
#
590
+
# pub struct Text;
591
+
# pub struct Integer;
592
+
#
593
+
# pub struct Bound<T>(T);
594
+
# pub struct SelectInt;
595
+
#
596
+
# impl Expression for SelectInt {
597
+
# type SqlType = Integer;
598
+
# }
599
+
#
600
+
# impl<T> Expression for Bound<T> {
601
+
# type SqlType = T;
602
+
# }
603
+
#
604
+
# impl AsExpression<Integer> for i32 {
605
+
# type Expression = Bound<Integer>;
606
+
# }
607
+
#
608
+
# impl AsExpression<Text> for &'_ str {
609
+
# type Expression = Bound<Text>;
610
+
# }
611
+
#
612
+
# impl<T> Foo for T where T: Expression {}
613
+
614
+
// Uncomment this line to change the recommendation.
615
+
// #[diagnostic::do_not_recommend]
616
+
impl<T, ST> AsExpression<ST> for T
617
+
where
618
+
T: Expression<SqlType = ST>,
619
+
{
620
+
type Expression = T;
621
+
}
622
+
623
+
trait Foo: Expression + Sized {
624
+
fn check<T>(&self, _: T) -> <T as AsExpression<<Self as Expression>::SqlType>>::Expression
625
+
where
626
+
T: AsExpression<Self::SqlType>,
627
+
{
628
+
todo!()
629
+
}
630
+
}
631
+
632
+
fn main() {
633
+
SelectInt.check("bar");
634
+
}
635
+
```
636
+
637
+
The `SelectInt` type's `check` method is expecting an `Integer` type. Calling it with an i32 type works, as it gets converted to an `Integer` by the `AsExpression` trait. However, calling it with a string does not, and generates a an error that may look like this:
638
+
639
+
```text
640
+
error[E0277]: the trait bound `&str: Expression` is not satisfied
641
+
--> src/main.rs:53:15
642
+
|
643
+
53 | SelectInt.check("bar");
644
+
| ^^^^^ the trait `Expression` is not implemented for `&str`
645
+
|
646
+
= help: the following other types implement trait `Expression`:
647
+
Bound<T>
648
+
SelectInt
649
+
note: required for `&str` to implement `AsExpression<Integer>`
650
+
--> src/main.rs:45:13
651
+
|
652
+
45 | impl<T, ST> AsExpression<ST> for T
653
+
| ^^^^^^^^^^^^^^^^ ^
654
+
46 | where
655
+
47 | T: Expression<SqlType = ST>,
656
+
| ------------------------ unsatisfied trait bound introduced here
657
+
```
658
+
659
+
By adding the `#[diagnostic::do_no_recommend]` attribute to the blanket `impl` for `AsExpression`, the message changes to:
660
+
661
+
```text
662
+
error[E0277]: the trait bound `&str: AsExpression<Integer>` is not satisfied
663
+
--> src/main.rs:53:15
664
+
|
665
+
53 | SelectInt.check("bar");
666
+
| ^^^^^ the trait `AsExpression<Integer>` is not implemented for `&str`
667
+
|
668
+
= help: the trait `AsExpression<Integer>` is not implemented for `&str`
669
+
but trait `AsExpression<Text>` is implemented for it
670
+
= help: for that trait implementation, expected `Text`, found `Integer`
671
+
```
672
+
673
+
The first error message includes a somewhat confusing error message about the relationship of `&str` and `Expression`, as well as the unsatisfied trait bound in the blanket impl. After adding `#[diagnostic::do_no_recommend]`, it no longer considers the blanket impl for the recommendation. The message should be a little clearer, with an indication that a string cannot be converted to an `Integer`.
0 commit comments