Better docs for PartialEq

Author: hkBst

library/core/src/cmp.rs

@@ -249,14 +249,23 @@ use crate::ops::ControlFlow;
 #[rustc_diagnostic_item = "PartialEq"]
 #[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
 pub const trait PartialEq<Rhs: PointeeSized = Self>: PointeeSized {
-    /// Tests for `self` and `other` values to be equal, and is used by `==`.
+    /// Equality operator `==`.
+    ///
+    /// Implementation of the "is equal to" operator `==`:
+    /// tests whether its arguments are equal.
     #[must_use]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[rustc_diagnostic_item = "cmp_partialeq_eq"]
     fn eq(&self, other: &Rhs) -> bool;
 
-    /// Tests for `!=`. The default implementation is almost always sufficient,
-    /// and should not be overridden without very good reason.
+    /// Inequality operator `!=`.
+    ///
+    /// Implementation of the "is not equal to" or "is different from" operator `!=`:
+    /// tests whether its arguments are different.
+    ///
+    /// # Default implementation
+    /// The default implementation of the inequality operator simply calls
+    /// the implementation of the equality operator and negates the result.
     #[inline]
     #[must_use]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1857,19 +1866,31 @@ mod impls {
     use crate::ops::ControlFlow::{self, Break, Continue};
     use crate::panic::const_assert;
 
-    macro_rules! partial_eq_impl {
+    /// Implements `PartialEq` for primitive types.
+    ///
+    /// Primitive types have a compiler-defined primitive implementation of `==` and `!=`.
+    /// This implements the `PartialEq` trait is terms of those primitive implementations.
+    ///
+    /// NOTE: Calling this on a non-primitive type (such as `()`)
+    /// leads to infinitely recursive implementations.
+    macro_rules! impl_partial_eq_for_primitive {
         ($($t:ty)*) => ($(
             #[stable(feature = "rust1", since = "1.0.0")]
             #[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
             impl const PartialEq for $t {
                 #[inline]
                 fn eq(&self, other: &Self) -> bool { *self == *other }
+                // Override the default to use the primitive implementation for `!=`.
                 #[inline]
                 fn ne(&self, other: &Self) -> bool { *self != *other }
             }
         )*)
     }
 
+    impl_partial_eq_for_primitive! {
+        bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128
+    }
+
     #[stable(feature = "rust1", since = "1.0.0")]
     #[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
     impl const PartialEq for () {
@@ -1883,10 +1904,6 @@ mod impls {
         }
     }
 
-    partial_eq_impl! {
-        bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128
-    }
-
     macro_rules! eq_impl {
         ($($t:ty)*) => ($(
             #[stable(feature = "rust1", since = "1.0.0")]

tests/ui/type-alias-impl-trait/self-referential-2.current.stderr

@@ -9,7 +9,7 @@ LL |     42_i32
 help: the trait `PartialEq<Foo>` is not implemented for `i32`
       but trait `PartialEq<i32>` is implemented for it
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error: aborting due to 1 previous error
 

tests/ui/type-alias-impl-trait/self-referential-3.stderr

@@ -10,7 +10,7 @@ LL |     i
    = help: the trait `PartialEq<Bar<'a, 'b>>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error: aborting due to 1 previous error
 

tests/ui/type-alias-impl-trait/self-referential-4.stderr

@@ -9,7 +9,7 @@ LL |     i
    = help: the trait `PartialEq<Bar<'b, 'static>>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error[E0277]: can't compare `&i32` with `Foo<'static, 'b>`
   --> $DIR/self-referential-4.rs:13:31
@@ -22,7 +22,7 @@ LL |     i
    = help: the trait `PartialEq<Foo<'static, 'b>>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error[E0277]: can't compare `&i32` with `Moo<'static, 'a>`
   --> $DIR/self-referential-4.rs:20:31
@@ -35,7 +35,7 @@ LL |     i
    = help: the trait `PartialEq<Moo<'static, 'a>>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error: aborting due to 3 previous errors
 

tests/ui/type-alias-impl-trait/self-referential.stderr

@@ -10,7 +10,7 @@ LL |     i
    = help: the trait `PartialEq<Bar<'b, 'a>>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error[E0277]: can't compare `&i32` with `(i32, Foo<'a, 'b>::{opaque#0}<'a, 'b>)`
   --> $DIR/self-referential.rs:14:31
@@ -24,7 +24,7 @@ LL |     (42, i)
    = help: the trait `PartialEq<(i32, Foo<'a, 'b>::{opaque#0}<'a, 'b>)>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error[E0277]: can't compare `&i32` with `(i32, Moo<'b, 'a>::{opaque#0}<'b, 'a>)`
   --> $DIR/self-referential.rs:22:31
@@ -38,7 +38,7 @@ LL |     (42, i)
    = help: the trait `PartialEq<(i32, Moo<'b, 'a>::{opaque#0}<'b, 'a>)>` is not implemented for `&i32`
 help: the trait `PartialEq` is implemented for `i32`
   --> $SRC_DIR/core/src/cmp.rs:LL:COL
-   = note: this error originates in the macro `partial_eq_impl` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `impl_partial_eq_for_primitive` (in Nightly builds, run with -Z macro-backtrace for more info)
 
 error: aborting due to 3 previous errors